怎么实现Java开发SpringBoot集成接口文档

本篇内容介绍了“怎么实现Java开发SpringBoot集成接口文档”的有关知识，在实际案例的操作过程中，不少人都会遇到这样的困境，接下来就让小编带领大家学习一下如何处理这些情况吧！希望大家仔细阅读，能够学有所成！

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>./class="lazy" data-src/main/resources/smart-doc.json</configFile>    <projectName>Smart-Doc初体验</projectName>  </configuration></plugin>

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

新建配置文件smart-doc.json

{  "outPath": "class="lazy" data-src/main/resources/static/doc"}

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

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

//生成htmlmvn -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": "class="lazy" data-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 为例配置后端跨域：

@Configurationpublic 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("*");                corsConfiguration.addAllowedMethod("*");        urlBasedCorsConfigurationSource.registerCorsConfiguration("/**", corsConfiguration);        return new CorsFilter(urlBasedCorsConfigurationSource);    }}

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

2. 通用响应体

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

{  "responseBodyAdvice":{            -- 通用响应体    "className":"com.jianzh6.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": "class="lazy" data-src/main/resources/static/doc",  "createDebugPage": true,  "allInOneDocFileName":"index.html",  "projectName": "初识smart-doc",  "packageFilters": "com.jianzh6.blog.smartdoc.*",  "errorCodeDictionaries": [{    "title": "title",    "enumClassName": "com.jianzh6.blog.base.ReturnCode",    "codeField": "code",    "descField": "message"  }],  "responseBodyAdvice":{    "className":"com.jianzh6.blog.base.ResultData"  },  "requestHeaders": [{    "name": "token",    "type": "string",    "desc": "自定义请求头 - token",    "value":"123456",    "required": false,    "since": "-",    "pathPatterns": "/smart/say",    "excludePathPatterns":"/smart/add,/smart/edit"  }]}

“怎么实现Java开发SpringBoot集成接口文档”的内容就介绍到这里了，感谢大家的阅读。如果想了解更多行业相关的知识可以关注编程网网站，小编将为大家输出更多高质量的实用文章！