Smart-doc：零注解侵入的API接口文档生成插件

零注解侵入的API接口文档生成插件——Smart-doc

smart-doc 是一款同时支持 JAVA REST API 和 Apache Dubbo RPC 接口文档生成的工具，在业内率先提出基于JAVA泛型定义推导的理念， 完全基于接口源码来分析生成接口文档，不采用任何注解侵入到业务代码中。 你只需要按照java-doc标准编写注释， smart-doc就能帮你生成一个简易明了的Markdown、HTML5、Postman Collection2.0+、OpenAPI 3.0+的文档。

1 特性

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

2 与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 中渲染展示。

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

与 Swagger 对比最大的区别在于：

  1. Smart-doc 不需要启动，直接运行插件就可以生成api文档；
  2. Smart-doc 不需要编写复杂注解来生成文档；

3 使用和实践

3.1 引入maven依赖

		<build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
            <plugin>
                <groupId>com.github.shalousun</groupId>
                <artifactId>smart-doc-maven-plugin</artifactId>
                <version>2.4.8</version>
                <configuration>
                    <!--指定生成文档的使用的配置文件,配置文件放在自己的项目中-->
                    <configFile>./src/main/resources/smart-doc.json</configFile>
                    <!--指定项目名称，推荐使用动态参数，例如${project.description}-->
                    <!--如果smart-doc.json中和此处都未设置projectName，2.3.4开始，插件自动采用pom中的projectName作为设置-->
                    <projectName>${project.description}</projectName>
                </configuration>
                <executions>
                    <execution>
                        <!--如果不需要在执行编译时启动smart-doc，则将phase注释掉-->
                        <phase>compile</phase>
                        <goals>
                            <!--smart-doc提供了html、openapi、markdown等goal，可按需配置-->
                            <goal>html</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>

3.2 配置 Smart-doc 插件

结合我司实际使用情况来看，我们采用的是Smart-doc + Apifox 来生成、解析接口文档进行前后端协作开发。在resource下创建一个smart-doc.json文件，内容如下：

{
  "serverUrl": "http://123.xxx.xxx.165:18888",
  "pathPrefix": "/api/v1",
  "isStrict": false,
  "allInOne": true,
  "nameStyle": "original",
  "outPath": "src/main/resources/templates/apidoc",
  "coverOld": true,
  "createDebugPage": true,
  "packageFilters": "com.xxx.insurance.agency.app.controller.temp.*",
  "md5EncryptedHtmlName": false,
  "style": "xt256",
  "projectName": "xxx App-Console API",
  "skipTransientField": true,
  "sortByTitle": false,
  "showAuthor": true,
  "requestFieldToUnderline": false,
  "responseFieldToUnderline": false,
  "inlineEnum": true,
  "recursionLimit": 7,
  "allInOneDocFileName": "index.html",
  "requestExample": "true",
  "responseExample": "true",
  "version": "v0.0.1",
  "responseBodyAdvice": {
    "className": "com.xxx.ddd.base.CommonResponse"
  },
  "requestHeaders": [{
    "name": "X-xxx-Webservice-Id",
    "type": "string",
    "desc": "请求特有的webServiceId",
    "value": "xxx",
    "required": true
  },
    {
      "name": "Authorization",
      "type": "string",
      "desc": "Bearer开头的登陆校验",
      "value":"Bearer ",
      "required": true
    }]
}

介绍一些重要的配置参数，其中:

  • outPath 表示api文档输出路径;

  • serverUrl 表示服务url，便于前端发起请求联调；

  • pathPrefix 表示路径前缀，注意在Controller层无需重复写requestMapping的前缀；

  • packageFilters 表示仅检测该包路径下的Controller类；

  • requestHeaders 表示自动添加的请求头;

  • responseBodyAdvice表示为我们自动增强的切面类;

    其他参数以及更多参数介绍请参考官网：https://smart-doc-group.github.io/zh/

image-20240713181743723

3.3 使用maven插件生成api文档

image-20240713181926701

也可以使用maven命令生成：

// Http Restful api文档
//生成 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
// 生成 OpenApi 3.0
mvn -Dfile.encoding=UTF-8 smart-doc:openapi

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

生成后如下图所示：

image-20240713182318386

3.4 实践效果

如果采用postman管理api接口，可以生成postman的json格式的文档，如果使用apifox可以生成markdown或openapi导入，导入api文档后如下图所示：

image-20240713183231687

生成的html文档如下所示：

image-20240713183130060

以上。

本博客内容仅供个人学习使用，禁止用于商业用途。转载需注明出处并链接至原文。

posted @ 2024-07-13 18:36  爱吃麦辣鸡翅  阅读(185)  评论(0)  编辑  收藏  举报