Java开发SpringBoot集成接口文档实现示例

目录
  • swagger vs smart-doc
    • Swagger的代码侵入性比较强
    • 原生swagger不支持接口的参数分组
    • 简单罗列一下smart-doc的优点
  • SpringBoot集成 smart-doc
    • 引入依赖,版本选择最新版本
    • 新建配置文件smart-doc.json
    • 通过执行maven 命令生成对应的接口文档
    • 访问接口文档
  • 功能增强
    • 1. 开启调试
    • 2. 通用响应体
    • 3. 自定义Header
    • 4. 参数分组
    • 5. idea配置doc
    • 6. 完整配置
  • 小结

之前我在SpringBoot老鸟系列中专门花了大量的篇幅详细介绍如何集成Swagger,以及如何对Swagger进行扩展让其支持接口参数分组功能。

详情可见:SpringBoot 如何生成接口文档,老鸟们都这么玩的!

可是当我接触到另一个接口文档工具 smart-doc后,我觉得它比Swagger更适合集成在项目中,更适合老鸟们。今天我们就来介绍一下smart-doc组件的使用,作为对老鸟系列文章的一个补充。

swagger vs smart-doc

首先我们先看一下Swagger组件目前存在的主要问题:

Swagger的代码侵入性比较强

这个很容易理解,要让Swagger生成接口文档必须要给方法或字段添加对应的注解,是存在代码侵入的。

原生swagger不支持接口的参数分组

对于有做参数分组的接口,原生的Swagger并未支持,虽然我们通过扩展其组件可以让其支持参数分组,但是毕竟要开发,而且还未支持最新的Swagger3版本。

那作为对比,smart-doc 是基于接口源码分析来生成接口文档,完全做到零注解侵入,你只需要按照java标准注释的写,smart-doc就能帮你生成一个简易明了的markdown 或是一个像GitBook样式的静态html文档。官方地址:https://gitee.com/smart-doc-team/smart-doc

简单罗列一下smart-doc的优点

零注解、零学习成本、只需要写标准java注释即可生成文档。

基于源代码接口定义自动推导,强大的返回结构推导。

支持Spring MVC,Spring Boot,Spring Boot Web Flux(controller书写方式)。

支持Callable,Future,CompletableFuture等异步接口返回的推导。

支持JavaBean上的JSR303参数校验规范,支持参数分组。

对一些常用字段定义能够生成有效的模拟值。…

接下来我们来看看SpringBoot中如何集成smart-doc。

SpringBoot集成 smart-doc

smart-doc支持多种方式生成接口文档:maven插件、gradle插件、单元测试(不推荐),这里我才用的是基于maven插件生成,步骤如下:

引入依赖,版本选择最新版本

<!--引入smart-doc-->
<plugin>
  <groupId>com.github.shalousun</groupId>
  <artifactId>smart-doc-maven-plugin</artifactId>
  <version>2.2.7</version>
  <configuration>
    <configFile>./src/main/resources/smart-doc.json</configFile>
    <projectName>Smart-Doc初体验</projectName>
  </configuration>
</plugin>

重点在 configFile中指定smart-doc配置文件 smart-doc.json

新建配置文件smart-doc.json

{
  "outPath": "src/main/resources/static/doc"
}

指定smart-doc生成的文档路径,其他配置项可以参考官方wiki。

通过执行maven 命令生成对应的接口文档

//生成html
mvn -Dfile.encoding=UTF-8 smart-doc:html

当然也可以通过idea中的maven插件生成

访问接口文档

生成接口文档后我们通过 http://localhost:8080/doc/api.html 查看,效果如下:

看到这里的同学可能会呵呵一笑,就这?啥也没有呀!这还想让我替换Swagger?

别急,刚刚只是体验了smart-doc的基础功能,接下来我们通过丰富smart-doc的配置文件内容来增强其功能。

功能增强

1. 开启调试

一个优秀的接口文档工具调试功能必不能少,smart-doc支持在线调试功能,只需要加入如下几个配置项:

{
  "serverUrl": "http://localhost:8080",      -- 服务器地址
  "allInOne": true,                -- 是否将文档合并到一个文件中,一般推荐为true
  "outPath": "src/main/resources/static/doc",  -- 指定文档的输出路径
  "createDebugPage": true,           -- 开启测试
  "allInOneDocFileName":"index.html",      -- 自定义文档名称
  "projectName": "初识smart-doc"        -- 项目名称
}

通过"createDebugPage": true 开启debug功能,在让生成smart-doc生成文档时直接放入到 static/doc/下,这样可以直接启动程序访问页面 http://localhost:8080/doc/index.html 进行开发调试。

有的开发人员直接在idea中使用【Open In Browser】打开smart-doc生成的debug页面,如果非要这做,前端js请求后台接口时就出现了跨域。因此你需要在后端配置跨域。

这里以 SpringBoot2.3.x 为例配置后端跨域:

@Configuration
public class WebMvcAutoConfig implements WebMvcConfigurer {

    @Bean
    public CorsFilter corsFilter() {
        final UrlBasedCorsConfigurationSource urlBasedCorsConfigurationSource = new UrlBasedCorsConfigurationSource();
        final CorsConfiguration corsConfiguration = new CorsConfiguration();
        /* 是否允许请求带有验证信息 */
        corsConfiguration.setAllowCredentials(true);
        /* 允许访问的客户端域名 */
        corsConfiguration.addAllowedOrigin("*");
        /* 允许服务端访问的客户端请求头 */
        corsConfiguration.addAllowedHeader("*");
        /* 允许访问的方法名,GET POST等 */
        corsConfiguration.addAllowedMethod("*");
        urlBasedCorsConfigurationSource.registerCorsConfiguration("/**", corsConfiguration);
        return new CorsFilter(urlBasedCorsConfigurationSource);
    }
}

开启跨域后我们就可以直接在静态接口页面中进行调试了。

2. 通用响应体

在 “SpringBoot 如何统一后端返回格式?老鸟们都是这样玩的!”一文中我们通过实现 ResponseBodyAdvice对所有返回值进行了包装,给前端返回统一的数据结构ResultData,我们需要让其在接口文档中也有此功能,在配置文件追加配置内容:

{
  "responseBodyAdvice":{            -- 通用响应体
    "className":"com.jianzh5.blog.base.ResultData"
  }
}

3. 自定义Header

在前后端分离项目中我们一般需要在请求接口时设置一个请求头,如token,Authorization等…后端根据请求头判断是否为系统合法用户,目前smart-doc也对其提供了支持。

在smart-doc配置文件 smart-doc.json中继续追加如下配置内容:

"requestHeaders": [ //设置请求头,没有需求可以不设置
    {
      "name": "token",//请求头名称
      "type": "string",//请求头类型
      "desc": "自定义请求头 - token",//请求头描述信息
      "value":"123456",//不设置默认null
      "required": false,//是否必须
      "since": "-",//什么版本添加的改请求头
      "pathPatterns": "/smart/say",//只有以/smart/say 开头的url才会有此请求头
      "excludePathPatterns":"/smart/add,/smart/edit" // url=/app/page/将不会有该请求头
    }
]

效果如下:

4. 参数分组

演示一下smart-doc对于参数分组的支持

新增操作时,age、level为必填项,sex为非必填。

编辑操作时,id,appid,leven为必填项,sex为非必填。

通过上面的效果可以看出smart-doc对于参数分组是完全支持的。

5. idea配置doc

自定义的tag默认是不会自动提示的,需要用户在idea中进行设置。设置好后即可使用,下面以设置smart-doc自定义的mock tag为例,设置操作如下:

6. 完整配置

附上完整配置,如果还需要其他配置大家可以参考wiki自行引入。

{
  "serverUrl": "http://localhost:8080",
  "allInOne": true,
  "outPath": "src/main/resources/static/doc",
  "createDebugPage": true,
  "allInOneDocFileName":"index.html",
  "projectName": "初识smart-doc",
  "packageFilters": "com.jianzh5.blog.smartdoc.*",
  "errorCodeDictionaries": [{
    "title": "title",
    "enumClassName": "com.jianzh5.blog.base.ReturnCode",
    "codeField": "code",
    "descField": "message"
  }],
  "responseBodyAdvice":{
    "className":"com.jianzh5.blog.base.ResultData"
  },
  "requestHeaders": [{
    "name": "token",
    "type": "string",
    "desc": "自定义请求头 - token",
    "value":"123456",
    "required": false,
    "since": "-",
    "pathPatterns": "/smart/say",
    "excludePathPatterns":"/smart/add,/smart/edit"
  }]
}

小结

其实没什么可总结的,smart-doc使用非常简单,官方文档也非常详细,只要你会写标准的java注释就可以给你生成详细的接口文档。(如果你说你不会写注释,那这篇文章可能不太适合你) 而且在引入smart-doc后还可以强制要求开发人员给接口编写注释,保证团队代码风格不会出现很大差异。

以上就是Java开发SpringBoot集成接口文档实现示例的详细内容,更多关于SpringBoot集成接口文档的资料请关注我们其它相关文章!

(0)

相关推荐

  • Spring boot集成swagger2生成接口文档的全过程

    一.Swagger介绍 Swagger是一个规范和完整的框架,用于生成.描述.调用和可视化RESTful风格的web服务.目标是使客户端和文件系统作为服务器以同样的速度来更新文件的方法,参数和模型紧密集成到服务器.这个解释简单点来讲就是说,swagger是一款可以根据restful风格生成的接口开发文档,并且支持做测试的一款中间软件. 二.使用swagger优势 1.对于后端开发人员来说 不用再手写Wiki接口拼大量参数,避免手写错误 对代码侵入性低,采用全注解的方式,开发简单 方法参数名修改.

  • 教你利用springboot集成swagger并生成接口文档

    效果图 实现步骤 1.maven中引入jar包,不同版本的swagger可能页面效果不一样. <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.1</version> </dependency> <dependency> <groupId&g

  • SpringBoot如何自动生成API文档详解

    前言 在做项目的时候,如果项目是前后分离的,后端一定要和前端或者是移动端对接接口,那么问题来了,接口是不是要自己写给他们看,一般的会采用Excel或者Word来写,高级一点的就采用API管理平台手工录入,一个项目有上千上万个接口,天啊,这是多么大的工作量,在接口维护的时候更加痛苦,为了解决这样的事我们可以借助 japi这个项目来完成RESTFul文档的自动生成,完全基于注释生成,更多详细配置可查看https://github.com/dounine/japi. 使用说明 克隆项目下来 git c

  • SpringBoot如何优雅的整合Swagger Api自动生成文档

    目录 前言 整合swagger api 自定义配置信息 简单使用 Swagger常用注解 Api标记 ApiOperation标记 ApiParam标记 ApiModel标记 ApiModelProperty标记 ApiIgnore标记 ApiImplicitParam标记 ApiImplicitParams标记 总结 前言 一个好的可持续交付的项目,项目说明,和接口文档是必不可少的,swagger api 就可以帮我们很容易自动生成api 文档,不需要单独额外的去写,无侵入式,方便快捷大大减少

  • SpringBoot集成Swagger2生成接口文档的方法示例

    我们提供Restful接口的时候,API文档是尤为的重要,它承载着对接口的定义,描述等.它还是和API消费方沟通的重要工具.在实际情况中由于接口和文档存放的位置不同,我们很难及时的去维护文档.个人在实际的工作中就遇到过很多接口更新了很久,但是文档却还是老版本的情况,其实在这个时候这份文档就已经失去了它存在的意义.而 Swagger 是目前我见过的最好的API文档生成工具,使用起来也很方便,还可以直接调试我们的API.我们今天就来看下 Swagger2 与 SpringBoot 的结合. 准备工作

  • Java开发SpringBoot集成接口文档实现示例

    目录 swagger vs smart-doc Swagger的代码侵入性比较强 原生swagger不支持接口的参数分组 简单罗列一下smart-doc的优点 SpringBoot集成 smart-doc 引入依赖,版本选择最新版本 新建配置文件smart-doc.json 通过执行maven 命令生成对应的接口文档 访问接口文档 功能增强 1. 开启调试 2. 通用响应体 3. 自定义Header 4. 参数分组 5. idea配置doc 6. 完整配置 小结 之前我在SpringBoot老鸟

  • java集成开发SpringBoot生成接口文档示例实现

    目录 为什么要用Swagger ? Swagger集成 第一步: 引入依赖包 第二步:修改配置文件 第三步,配置API接口 Unable to infer base url For input string: "" Swagger美化 第一步: 引入依赖包 第二步:启用knife4j增强 Swagger参数分组 分组使用说明 1.在bean对象的属性里配置如下注释 2.在接口参数的时候加入组规则校验 小结 大家好,我是飘渺. SpringBoot老鸟系列的文章已经写了两篇,每篇的阅读反

  • golang组件swagger生成接口文档实践示例

    目录 swagger介绍 gin-swagger实战 第一步:添加注释 第二步:生成接口文档数据 第三步:引入gin-swagger渲染文档数据 swagger介绍 Swagger本质上是一种用于描述使用JSON表示的RESTful API的接口描述语言.Swagger与一组开源软件工具一起使用,以设计.构建.记录和使用RESTful Web服务.Swagger包括自动文档,代码生成和测试用例生成. 在前后端分离的项目开发过程中,如果后端同学能够提供一份清晰明了的接口文档,那么就能极大地提高大家

  • JAVA实现PDF转HTML文档的示例代码

    本文是基于PDF文档转PNG图片,然后进行图片拼接,拼接后的图片转为base64字符串,然后拼接html文档写入html文件实现PDF文档转HTML文档. 引入Maven依赖 <!-- https://mvnrepository.com/artifact/org.apache.pdfbox/pdfbox --> <dependency> <groupId>org.apache.pdfbox</groupId> <artifactId>pdfbox

  • Django+RestFramework API接口及接口文档并返回json数据操作

    系统:ubuntu18.04 x64 GitHub:https://github.com/xingjidemimi/DjangoAPI.git 安装 pip install django==2.1.5 pip install djangorestframework # rest api pip install coreapi pygments markdown # 自动化接口文档 API示例 创建django项目 django-admin startproject DjangoAPI 创建应用

  • java快速生成接口文档的三种解决方案

    目录 前言 方案一,使用japidocs 基本用法 方案2,swagger + knife4j 生成步骤 方案3,开源的接口文档生成工具 总结 前言 常常在项目收尾阶段,客户需要项目的接口文档,或者是一个大的sass平台,各个产品之间互相调用的时候,需要对方提供接口文档 通常来说,接口文档属于产品的技术沉淀,是一个长期积累的过程,然而,很多时候,开发阶段并不会想的那么多,结果到了需要接口文档的时候总是疲于应付,情急之下,往往采用最笨拙的办法,就是对照着项目代码,一个个拷贝吧 下面针对这个情况,小

  • SpringBoot中整合knife4j接口文档的实践

    在项目开发中,web项目的前后端分离开发,APP开发,需要由前后端工程师共同定义接口,编写接口文档,之后大家都根据这个接口文档进行开发,到项目结束前都要一直维护 接口文档使得项目开发过程中前后端工程师有一个统一的文件进行沟通交流开发,项目维护中或者项目人员更迭,方便后期人员查看.维护 一.界面先赏 1.首页 2.接口文档 3.调试 二.整合 knife4j 1.引入 maven 依赖 <!-- knife4j接口文档 start --> <dependency> <group

  • Spring Boot项目集成Knife4j接口文档的实例代码

    目录 1.在pom.xml引入依赖包 2.创建Knife4j配置文件 3.使用Knife4j注解 4.全局参数 Knife4j就相当于是swagger的升级版,对于我来说,它比swagger要好用得多 1.在pom.xml引入依赖包 <!-- Swagger配置依赖knife4j --> <dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>knife4j-spring-b

随机推荐

其他