自动生成接口文档、Smart-doc（Maven插件）使用教程

转自：https://blog.csdn.net/qq_40124555/article/details/126629409

参考：https://blog.csdn.net/weixin_40776321/article/details/120170756

参考：https://blog.csdn.net/qq_15901351/article/details/111630512

smart-doc介绍

一个 java restful api 文档生成工具，不用像Swagger一样写大量注解，完全基于接口源码分析来生成接口文档，但是需要按照 java的标准注释写。

完全基于接口源码来分析生成接口文档，不采用任何注解侵入到业务代码中。

你只需要按照java-doc标准编写注释， smart-doc就能帮你生成一个简易明了的Markdown、HTML5、Postman ollection2.0+、OpenAPI 3.0+的文档。

注意：需要完全按照java的标准注释，如果方法注释包含特殊符号或者换行的话，生成的json是会出现格式错误，但是不影响相关的html使用。

关于smart-doc

smart-doc特性

  • 零注解、零学习成本、只需要写标准JAVA注释。
  • 基于源代码接口定义自动推导，强大的返回结构推导。
  • 支持Spring MVC、Spring Boot、Spring Boot Web Flux(Controller书写方式)Feign。
  • 支持Callable、Future、CompletableFuture等异步接口返回的推导。
  • 支持JavaBean上的JSR303参数校验规范，包括分组验证。
  • 对JSON请求参数的接口能够自动生成模拟JSON参数。
  • 对一些常用字段定义能够生成有效的模拟值。
  • 支持生成JSON返回值示例。
  • 支持从项目外部加载源代码来生成字段注释(包括标准规范发布的jar包)。
  • 支持生成多种格式文档：Markdown、HTML5、Asciidoctor、Postman Collection、OpenAPI 3.0。 开放文档数据，可自由实现接入文档管理系统。
  • 支持导出错误码和定义在代码中的各种字典码到接口文档。
  • 支持Maven、Gradle插件式轻松集成。
  • 支持Apache Dubbo RPC接口文档生成。
  • debug接口调试html5页面完全支持文件上传，下载(@download tag标记下载方法)测试。

smart-doc的最佳搭档

smart-doc + Torna 组成的文档生成和管理解决方案，使用smart-doc无侵入完成JAVA源代码分析和提取注释生成API文档，自动将文档推送到Torna企业级接口文档管理平台。

谁在使用smart-doc

smart-doc的优缺点

简单总结了几个特别明显以及我认为最关键的几个优点如下：

  • 非侵入式接口文档生成
  • 需要按照java文档注释规范对接口及相关对象添加注释
  • 编译文件后需要手动运行插件生成接口文档
  • 配置简单，只需要引入插件，配置文档输出位置即可。相关更加复杂的配置根据需要自行配置。
  • 无需启动项目，生成文档后可直接浏览

缺点
我总结了一下我使用过程中的缺点，在此我仅代表我自己提出的缺点如下

  • 生成的openapi.json数据时，不支持泛型的多层嵌套解析，导致不同接口的responseBody解析为一个。比如接口返回为：ResultVO<DefinePage<AiOptimizationCampaignReportVO>>，解析成ResultVODefinePage（新版本已解决）

smart-doc和swagger区别比较

功能特性 smart-doc swagger
代码侵入 无 注解侵入性严重
集成复杂度 简单，只需插件 偏复杂
插件支持 有 gradle 和 maven 插件 无插件
openapi 规范支持 支持 openapi 3.0 完全支持 openapi 的版本
CI 构建集成 可在 ci 构建阶段使用maven 或者 gradle 命令启动插件生成文档 不支持
集中化文档中心集成 已经和 torna 企业级接口文档管理平台对接 不支持
维护持续性 值得信赖，开源后用户基础多，一直持续维护 全球用户多，开源维护值得信赖
接口 debug 2.0.0 版本开始已经支持 debug，页面比 swagger 漂亮太多了。 支持

Smart-doc 从 2.0.0 后几乎实现了 swagger ui 的功能，并且比 swagger ui 更简洁大方，也更符合国内开发者的诉求。当然 smart-doc 的功能也已经超过了 swagger 为 java 开发者提供的功能。当然 smart-doc 本身是只支持扫描代码生成 openapi 3.0 的文档的，也可以将生成的 openapi 3.0 文档导入到其他 ui 中渲染展示。

swagger 生成 离线的文档 需要借助第三方jar包实现，而 smart-doc 直接 运行 test 方法就可以直接导出 md，html，asciidoc 等格式文档。

设计思路不同，smart-doc 是基于 源码分析的，它生成api文档是通过分析JAVA源码主要是通过 注释 和 系统自带注解，来实现文档的 生成，而 swagger 是运行时 自动生成在线文档，并且 生成 测试 接口的 案例。由于他们设计思路 理念 不一样，swagger2 使用过程需要使用它定义的@API 相关注解，这样就污染了源码，代码入侵有点高，而smart -doc 就不一样了，主要是通过 注释 、解析/** */ 来生成API文档的 。这样基本上没有入侵性，很自由！

swagger

 

  • 侵入式接口文档生成
  • 每个接口及每个实体类都需要添加注解
  • 配置复杂，需要添加依赖然后需要添加相关配置
  • 编译后自动生成接口文档
  • 需要启动后才能查看，如果配置了安全框架还需要开放相关接口

smart-doc的使用姿势

姿势一

使用maven或者gradle插件进行一键生成对应的文档格式或者命令进行生成，在这里我只展示了maven插件的使用姿势。

使用

1. 添加依赖

 1             <!-- smart doc -->
 2             <plugin>
 3                 <groupId>com.github.shalousun</groupId>
 4                 <artifactId>smart-doc-maven-plugin</artifactId>
 5                 <version>2.2.6</version>
 6                 <configuration>
 7                     <!--指定生成文档的使用的配置文件,配置文件放在自己的项目中-->
 8                     <configFile>./src/main/resources/smart-doc.json</configFile>
 9                     <!--指定项目名称-->
10                     <projectName>测试</projectName>
11                     <!--smart-doc实现自动分析依赖树加载第三方依赖的源码，如果一些框架依赖库加载不到导致报错，这时请使用excludes排除掉-->
12                     <excludes>
13                         <!--格式为：groupId:artifactId;参考如下-->
14                         <exclude>com.alibaba:fastjson</exclude>
15                     </excludes>
16                     <!--自1.0.8版本开始，插件提供includes支持,配置了includes后插件会按照用户配置加载而不是自动加载，因此使用时需要注意-->
17                     <!--smart-doc能自动分析依赖树加载所有依赖源码，原则上会影响文档构建效率，因此你可以使用includes来让插件加载你配置的组件-->
18                     <includes>
19                         <!--格式为：groupId:artifactId;参考如下-->
20                         <include>com.alibaba:fastjson</include>
21                     </includes>
22                 </configuration>
23                 <executions>
24                     <execution>
25                         <!--如果不需要在执行编译时启动smart-doc，则将phase注释掉-->
26                         <phase>compile</phase>
27                         <goals>
28                             <!--smart-doc提供了html、openapi、markdown等goal，可按需配置-->
29                             <goal>html</goal>
30                         </goals>
31                     </execution>
32                 </executions>
33             </plugin>

如果配置<phase>clean|validate|compile|test|package|verify|install|site|deploy</phase>这些，可以在以上指令被触发时执行smart-doc文档生成

2. 配置文件

在resource下创建一个smart-doc.json文件，内容如下

{
  "outPath": "C:\\api", // 接口文档输出地址
  "serverUrl": "http://127.0.0.1:8090"// 请求路径
}




// 详细配置，按需设置
{
  "serverUrl": "http://127.0.0.1", //服务器地址,非必须。导出postman建议设置成http://{{server}}方便直接在postman直接设置环境变量
  "pathPrefix": "", //设置path前缀,非必须。如配置Servlet ContextPath 。@since 2.2.3
  "isStrict": false, //是否开启严格模式
  "allInOne": true,  //是否将文档合并到一个文件中，一般推荐为true
  "outPath": "D://md2", //指定文档的输出路径
  "coverOld": true,  //是否覆盖旧的文件，主要用于mardown文件覆盖
  "createDebugPage": true,//@since 2.0.0 smart-doc支持创建可以测试的html页面，仅在AllInOne模式中起作用。
  "packageFilters": "",//controller包过滤，多个包用英文逗号隔开，2.2.2开始需要采用正则：com.test.controller.*
  "md5EncryptedHtmlName": false,//只有每个controller生成一个html文件是才使用
  "style":"xt256", //基于highlight.js的代码高设置,可选值很多可查看码云wiki，喜欢配色统一简洁的同学可以不设置
  "projectName": "smart-doc",//配置自己的项目名称
  "skipTransientField": true,//目前未实现
  "sortByTitle":false,//接口标题排序，默认为false,@since 1.8.7版本开始
  "showAuthor":true,//是否显示接口作者名称，默认是true,不想显示可关闭
  "requestFieldToUnderline":true,//自动将驼峰入参字段在文档中转为下划线格式,//@since 1.8.7版本开始
  "responseFieldToUnderline":true,//自动将驼峰入参字段在文档中转为下划线格式,//@since 1.8.7版本开始
  "inlineEnum":true,//设置为true会将枚举详情展示到参数表中，默认关闭，//@since 1.8.8版本开始
  "recursionLimit":7,//设置允许递归执行的次数用于避免一些对象解析卡主，默认是7，正常为3次以内，//@since 1.8.8版本开始
  "allInOneDocFileName":"index.html",//自定义设置输出文档名称, @since 1.9.0
  "requestExample":"true",//是否将请求示例展示在文档中，默认true，@since 1.9.0
  "responseExample":"true",//是否将响应示例展示在文档中，默认为true，@since 1.9.0
  "requestParamsTable": true, //是否将请求参数表展示在文档中，默认true，@since 2.2.5
  "responseParamsTable": true //是否将响应参数表展示在文档中, 默认true，@since 2.2.5
  "urlSuffix":".do",//支持SpringMVC旧项目的url后缀,@since 2.1.0
  "displayActualType":false,//配置true会在注释栏自动显示泛型的真实类型短类名，@since 1.9.6
  "appKey": "20201216788835306945118208",// torna平台对接appKey,, @since 2.0.9
  "appToken": "c16931fa6590483fb7a4e85340fcbfef", //torna平台appToken,@since 2.0.9
  "secret": "W.ZyGMOB9Q0UqujVxnfi@.I#V&tUUYZR",//torna平台secret，@since 2.0.9
  "openUrl": "http://localhost:7700/api",//torna平台地址，填写自己的私有化部署地址@since 2.0.9
  "debugEnvName":"测试环境", //torna环境名称
  "debugEnvUrl":"http://127.0.0.1",//推送torna配置接口服务地址
  "tornaDebug":false,//启用会推送日志
  "ignoreRequestParams":[ //忽略请求参数对象，把不想生成文档的参数对象屏蔽掉，@since 1.9.2
     "org.springframework.ui.ModelMap"
   ],
  "dataDictionaries": [{ //配置数据字典，没有需求可以不设置
      "title": "http状态码字典", //数据字典的名称
      "enumClassName": "com.power.common.enums.HttpCodeEnum", //数据字典枚举类名称
      "codeField": "code",//数据字典字典码对应的字段名称
      "descField": "message"//数据字典对象的描述信息字典
  }],
  "errorCodeDictionaries": [{ //错误码列表，没有需求可以不设置
    "title": "title",
    "enumClassName": "com.power.common.enums.HttpCodeEnum", //错误码枚举类
    "codeField": "code",//错误码的code码字段名称
    "descField": "message"//错误码的描述信息对应的字段名
  }],
  "revisionLogs": [{ //文档变更记录，非必须
      "version": "1.0", //文档版本号
      "revisionTime": "2020-12-31 10:30", //文档修订时间
      "status": "update", //变更操作状态，一般为：创建、更新等
      "author": "author", //文档变更作者
      "remarks": "desc" //变更描述
    }
  ],
  "customResponseFields": [{ //自定义添加字段和注释，一般用户处理第三方jar包库，非必须
      "name": "code",//覆盖响应码字段
      "desc": "响应代码",//覆盖响应码的字段注释
      "ownerClassName": "org.springframework.data.domain.Pageable", //指定你要添加注释的类名
      "ignore":true, //设置true会被自动忽略掉不会出现在文档中
      "value": "00000"//设置响应码的值
  }],
  "customRequestFields": [{ //自定义请求体的注释，@since 2.1.3，非必须
       "name":"code", //属性名
       "desc":"状态码", //描述
       "ownerClassName":"com.xxx.constant.entity.Result", //属性对应的类全路径
       "value":"200", //默认值或者mock值
       "required":true, //是否必填
       "ignore":false //是否忽略
  }],
  "requestHeaders": [{ //设置请求头，没有需求可以不设置
      "name": "token",//请求头名称
      "type": "string",//请求头类型
      "desc": "desc",//请求头描述信息
      "value":"token请求头的值",//不设置默认null
      "required": false,//是否必须
      "since": "-",//什么版本添加的改请求头
      "pathPatterns": "/app/test/**",//请看https://gitee.com/smart-doc-team/smart-doc/wikis/请求头高级配置?sort_id=4178978
      "excludePathPatterns":"/app/page/**"//请看https://gitee.com/smart-doc-team/smart-doc/wikis/请求头高级配置?sort_id=4178978
  },{
      "name": "appkey",//请求头
      "type": "string",//请求头类型
      "desc": "desc",//请求头描述信息
      "value":"appkey请求头的值",//不设置默认null
      "required": false,//是否必须
      "pathPatterns": "/test/add,/testConstants/1.0",//正则表达式过滤请求头,url匹配上才会添加该请求头，多个正则用分号隔开
      "since": "-"//什么版本添加的改请求头
  }],
  "requestParams": [ //公共请求参数(通过拦截器处理的场景)，@since 2.2.3,没有需求请不要设置
    {
      "name": "configPathParam",//请求头名称
      "type": "string",//请求头类型
      "desc": "desc",//请求头描述信息
      "paramIn": "path",
      "value":"testPath",//不设置默认null
      "required": false,//是否必须
      "since": "-",//什么版本添加的改请求头
      "pathPatterns": "*",//正则表达式过滤请求头
      "excludePathPatterns":"/app/page/**" //参考请求头中的用法
    },
    {
      "name": "configQueryParam",//请求头名称
      "type": "string",//请求头类型
      "desc": "desc",//请求头描述信息
      "paramIn": "query",
      "value":"testQuery",//不设置默认null
      "required": false,//是否必须
      "since": "-",//什么版本添加的改请求头
      "pathPatterns": "*",//正则表达式过滤请求头
      "excludePathPatterns":"/app/page/**"
    }
  ],
  "rpcApiDependencies":[{ // 项目开放的dubbo api接口模块依赖，配置后输出到文档方便使用者集成
        "artifactId":"SpringBoot2-Dubbo-Api",
        "groupId":"com.demo",
        "version":"1.0.0"
   }],
  "rpcConsumerConfig": "src/main/resources/consumer-example.conf",//文档中添加dubbo consumer集成配置，用于方便集成方可以快速集成
  "apiObjectReplacements": [{ // 自smart-doc 1.8.5开始你可以使用自定义类覆盖其他类做文档渲染，非必须
      "className": "org.springframework.data.domain.Pageable",
      "replacementClassName": "com.power.doc.model.PageRequestDto" //自定义的PageRequestDto替换Pageable做文档渲染
  }],
  "apiConstants": [{//从1.8.9开始配置自己的常量类，smart-doc在解析到常量时自动替换为具体的值，非必须
        "constantsClassName": "com.power.doc.constants.RequestParamConstant"
  }],
  "responseBodyAdvice":{ //自smart-doc 1.9.8起，非必须项，ResponseBodyAdvice统一返回设置(不要随便配置根据项目的技术来配置)，可用ignoreResponseBodyAdvice tag来忽略
          "className":"com.power.common.model.CommonResult" //通用响应体
  },
  "requestBodyAdvice":{ ////自smart-doc 2.1.4 起，支持设置RequestBodyAdvice统一请求包装类，非必须
         "className":"com.power.common.model.CommonResult"
  },
  "groups": [ // @since 2.2.5, 对不同的controller进行分组
    {
      "name": "测试分组",
      "apis": "com.power.doc.controller.app.*"
    }
  ]
}

3. 在Maven中生成文档

也可以使用maven插件命令，使用maven插件命令如下：

//生成html
mvn -Dfile.encoding=UTF-8 smart-doc:html
//生成markdown
mvn -Dfile.encoding=UTF-8 smart-doc:markdown
//生成adoc
mvn -Dfile.encoding=UTF-8 smart-doc:adoc
//生成postman json数据
mvn -Dfile.encoding=UTF-8 smart-doc:postman
// 生成 Open Api 3.0+,Since smart-doc-maven-plugin 1.1.5
mvn -Dfile.encoding=UTF-8 smart-doc:openapi
// 生成文档推送到Torna平台
mvn -Dfile.encoding=UTF-8 smart-doc:torna-rest

// Apache Dubbo RPC文档
// Generate html
mvn -Dfile.encoding=UTF-8 smart-doc:rpc-html
// Generate markdown
mvn -Dfile.encoding=UTF-8 smart-doc:rpc-markdown
// Generate adoc
mvn -Dfile.encoding=UTF-8 smart-doc:rpc-adoc

// 生成dubbo接口文档推送到torna
mvn -Dfile.encoding=UTF-8 smart-doc:torna-rpc

优点：便捷，快速上手

缺点：每个服务各自指定smart-doc的配置文件smart-doc.json

姿势二

导入相关smart-doc依赖

1 <!--导入Smart-doc依赖-->
2 <dependency>
3     <groupId>com.github.shalousun</groupId>
4     <artifactId>smart-doc</artifactId>
5     <version>2.5.1</version>
6 </dependency>

手动为每个项目引入以上jar包，可以使用smart-doc.json配置文件也可以使用smart-doc自带的ApiConfig配置类进行手动配置。

使用单元测试测试API文档生成如下：

 1 @Test
 2 public void testBuilderControllersApi() {
 3     ApiConfig config = new ApiConfig();
 4     config.setServerUrl("http://localhost:8080");
 5     //当把AllInOne设置为true时，Smart-doc将会把所有接口生成到一个Markdown、HHTML或者AsciiDoc中
 6     config.setAllInOne(true);
 7 
 8     //HTML5文档，建议直接放到src/main/resources/static/doc下，Smart-doc提供一个配置常量HTML_DOC_OUT_PATH
 9     //源码---String HTML_DOC_OUT_PATH = "src/main/resources/static/doc";
10     config.setOutPath("src/main/resources/static/doc");
11 
12     // 设置接口包扫描路径过滤，如果不配置则Smart-doc默认扫描所有的接口类
13     // 配置多个报名有英文逗号隔开
14     config.setPackageFilters("com.***.Controller.*");
15 
16     //设置错误错列表，遍历自己的错误码设置给Smart-doc即可
17     List<ApiErrorCode> errorCodeList = new ArrayList<>();
18     for (HttpCodeEnum codeEnum : HttpCodeEnum.values()) {
19         ApiErrorCode errorCode = new ApiErrorCode();
20         errorCode.setValue(codeEnum.getCode()).setDesc(codeEnum.getMessage());
21         errorCodeList.add(errorCode);
22     }
23 
24     //不需要显示错误码,则可以不用设置错误码。
25     config.setErrorCodes(errorCodeList);
26     //生成Markdown文件
27     HtmlApiDocBuilder.buildApiDoc(config);
28 }

姿势三（公司内部推荐使用）

Q：为什么说公司内部建议使用呢？
答：每个公司都会有自己的maven仓库(几乎)，可以搞一些定制化的工具包，比如：日志、认证、链路、授权等。可以在工具包中加入smart-doc包进行简单开发。

可以这么做：
将smart-doc集成到工具包中，在工具包进行打包，提供给使用方，然后定制开发进行配置化管理

每个Java业务服务引入公共jar包，然后进行配置，自定义配置如下：

# 是否开启html生成，默认为false
smart-doc.html-enable=true
# html生成路径，默认为当前服务子目录doc下
smart-doc.out-path=/doc/
# 接口返回对象配置
smart-doc.response-class-name=com.sparkxmedia.xplatform.sd.api.common.result.ResultVO
# 自定义请求头
smart-doc.request-header.username=zane
smart-doc.request-header.user_id=1
smart-doc.request-header.authorization=test
# controller层包
smart-doc.package-filters=com.sparkxmedia.xplatform.sd.api.ai.controller.*,com.sparkxmedia.xplatform.sd.api.controller.*
# 如果使用swagger-ui替代smart-doc的html，则需配置获取openapi.json路径
springdoc.swagger-ui.url=/sd-api/doc/openapi.json

其核心代码如下：

 1 package com.cuizb.tools.starter.config.doc;
 2 
 3 import lombok.SneakyThrows;
 4 import lombok.extern.slf4j.Slf4j;
 5 import org.springframework.beans.factory.annotation.Autowired;
 6 import org.springframework.boot.context.properties.EnableConfigurationProperties;
 7 import org.springframework.context.annotation.Configuration;
 8 import org.springframework.util.ResourceUtils;
 9 import org.springframework.web.servlet.config.annotation.CorsRegistry;
10 import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
11 import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
12 
13 /**
14  * @author: Java技术债务
15  * @Date: 2021/6/6 20:03
16  * Describe: 跨域解决,映射生成的静态资源
17  */
18 @Slf4j
19 @Configuration
20 @EnableConfigurationProperties({ApiDocProperties.class})
21 public class WebMvcConfig implements WebMvcConfigurer {
22     @Autowired
23     private ApiDocProperties apiDocProperties;
24 
25     /**
26      * 解决跨域问题
27      * @param registry
28      */
29     @Override
30     public void addCorsMappings(CorsRegistry registry) {
31         registry.addMapping("/**")
32                 .allowedHeaders("*")
33                 .allowedMethods("*")
34                 .allowedOriginPatterns("/**")
35                 .maxAge(3600);
36     }
37 
38     @SneakyThrows
39     @Override
40     public void addResourceHandlers(ResourceHandlerRegistry registry) {
41         // 当前项目根路径
42         String rootPath = ResourceUtils.getURL("").getPath();
43         // 文档保存绝对路径
44         rootPath = rootPath.substring(0, rootPath.length() - 1) + apiDocProperties.getOutPath();
45         // 映射到当前项目根路径+用户自定义路径(当前仅支持当前项目下路径)
46         String resourcesPath;
47         if ("dev".equals(apiDocProperties.getProfileActive()) || "local".equals(apiDocProperties.getProfileActive())) {
48             resourcesPath = "file:///" + rootPath;
49         } else {
50             resourcesPath = "file:///" + apiDocProperties.getOutPath();
51         }
52 
53         log.info(">>>>>>>>>>>>>" + resourcesPath);
54         //配置静态资源映射
55         registry
56                 .addResourceHandler("/doc/static/**")
57                 .addResourceLocations(resourcesPath);
58     }
59 
60 }
 1 package com.cuizb.tools.starter.config.doc;
 2 
 3 import lombok.AllArgsConstructor;
 4 import lombok.Data;
 5 import lombok.NoArgsConstructor;
 6 import org.springframework.beans.factory.annotation.Value;
 7 import org.springframework.boot.context.properties.ConfigurationProperties;
 8 import org.springframework.context.annotation.Configuration;
 9 
10 import java.util.HashMap;
11 import java.util.Map;
12 
13 /**
14  * @author Java技术债务
15  * @date 2022-08-17 15:08
16  * Be in awe of every code modification
17  */
18 @Data
19 @AllArgsConstructor
20 @NoArgsConstructor
21 @Configuration
22 @ConfigurationProperties(prefix = "smart-doc")
23 public class ApiDocProperties {
24 
25     @Value("${server.port}")
26     private int port;
27 
28     @Value("${app.id}")
29     private String appId;
30 
31     @Value("${server.servlet.context-path:}")
32     private String pathFilter;
33 
34     @Value("${spring.profiles.active:dev}")
35     private String profileActive;
36 
37     private boolean htmlEnable;
38 
39     private String outPath;
40 
41     private String responseClassName;
42 
43     private Map<String, String> requestHeader = new HashMap<>();
44 
45     private String packageFilters;
46 }
 1 /**
 2  * @author Java技术债务
 3  * @date 2022-08-16 18:17
 4  * Be in awe of every code modification
 5  */
 6 @Slf4j
 7 @EnableConfigurationProperties({ApiDocProperties.class})
 8 @Controller
 9 //@RequestMapping("${spring.application.name}/doc")
10 @Profile({"dev", "local", "qa", "test", "sit", "uat"})
11 @RequestMapping("/doc")
12 public class DocController {
13     @Autowired
14     private ApiDocProperties apiDocProperties;
15 
16     private ApiDocConfig apiDocConfig;
17 
18     public DocController() {
19 
20     }
21 
22     @GetMapping("/openapi.json")
23     @ResponseBody
24     public String openapi() {
25         initApiDocConfig();
26         ApiConfig config = apiDocConfig.getApiConfig();
27 
28         return OpenApiBuilder.buildOpenApi(config).trim().replace(" ", "");
29     }
30      @GetMapping("/build")
31     public String buildHtml() {
32         initApiDocConfig();
33         ... ...
34     }
35 }

代码解释：

  • WebMvcConfig解决跨域以及文件映射，由开发人员决定是否使用smart-doc生成的API接口文档页面，因为有的已经使用了其他产品，可以将smart-doc生成的json同步到现有的产品，当然如果你只使用smart-doc的话，不需要配置文件映射。
  • ApiDocProperties自定义配置，开发人员只关心自己当前服务的smart-doc相关配置即可
  • DocController工具包中的uri进行资源访问，可以自定义html，openapi.json等路径。也可以自定义开发，生成json文件或者json字符串等。

当前为了适用本公司，简单的自定义了一些开发，以下是简单的配置了一些路径资源：

  • 获取openapi.json地址：http://localhost:port[/server-servlet-context-path]/doc/openapi.json
  • 构建html文件地址：http://localhost:port[/server-servlet-context-path]/doc/build
  • html接口文档地址：http://localhost:port[/server-servlet-context-path]/doc/static/index.html

如果你想使用这种的话，你可以继续研究与开发。。。

总结

可以入手使用，关键是零侵入，还支持dubbo方式（虽然我未体验使用此方式）

官方开源地址：https://gitee.com/smart-doc-team

 

零注解、零学习成本、只需要写标准JAVA注释。基于源代码接口定义自动推导，强大的返回结构推导。支持Spring MVC、Spring Boot、Spring Boot Web Flux(Controller书写方式)Feign。支持Callable、Future、CompletableFuture等异步接口返回的推导。支持JavaBean上的JSR303参数校验规范，包括分组验证。对JSON请求参数的接口能够自动生成模拟JSON参数。对一些常用字段定义能够生成有效的模拟值。支持生成JSON返回值示例。支持从项目外部加载源代码来生成字段注释(包括标准规范发布的jar包)。支持生成多种格式文档：Markdown、HTML5、Asciidoctor、Postman Collection、OpenAPI 3.0。 开放文档数据，可自由实现接入文档管理系统。支持导出错误码和定义在代码中的各种字典码到接口文档。支持Maven、Gradle插件式轻松集成。支持Apache Dubbo RPC接口文档生成。debug接口调试html5页面完全支持文件上传，下载(@download tag标记下载方法)测试。————————————————版权声明：本文为CSDN博主「Java技术债务」的原创文章，遵循CC 4.0 BY-SA版权协议，转载请附上原文出处链接及本声明。原文链接：https://blog.csdn.net/qq_40124555/article/details/126629409
posted @ 2022-11-16 15:19  Boblim  阅读(4698)  评论(0)  编辑  收藏  举报