【D3S】REST接口文档自动生成 - 集成smart-doc并同步配置到Torna

一、引言

D3S（DDD with SpringBoot）为本作者使用DDD过程中开发的框架，目前已可公开查看源码，笔者正在持续完善该框架，争取打造一个可落地的DDD框架。而在开发D3S框架的过程中，相较Swagger、OpenApi以注解侵入代码的方式，笔者选择了smart-doc以代码注释的形式来完成REST接口文档的生成，配合Torna可以方便完成接口文档同步与管理的工作。之前笔者也成使用过YAPI，但是目前YAPI对OpenApi 3.0支持的不是很好，实测将OAS 3.0的接口文档JSON导入YAPI后，会出现接口返回结果为空的情况，实测Torna对OAS 3.0支持的较为完善，同时Torna也支持直接导入Swagger/OAS文档（JSON/YAML）或URL链接导入，故现阶段如果想选择一款文档管理工具，还是比较推荐Torna。
在这里插入图片描述

关于smart-doc与Swagger、OpenApi等的比较可参见笔者之前的博客：
SpringBoot应用生成RESTful API文档 - Swagger 2.0、OAS 3.0、Springfox、Springdoc、Smart-doc

接下来本文主要介绍如何通过maven插件集成smart-doc，并同步接口文档到Torna。由于smart-doc会直接解析代码注释，所以注释规范的代码几乎不需要额外的修改，如此也能养成团队规范代码注释的习惯。

二、maven插件

配置如下smart-doc-maven-plugin插件：

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    
    <properties>
        <smart.doc.version>2.6.1</smart.doc.version>
        <smart.doc.goal>openapi</smart.doc.goal>
    </properties>

    <build>
        <pluginManagement>
            <plugins>
                <!-- smart-doc插件定义 -->
                <plugin>
                    <groupId>com.github.shalousun</groupId>
                    <artifactId>smart-doc-maven-plugin</artifactId>
                    <version>${smart.doc.version}</version>
                    <configuration>
                        <!--指定生成文档的使用的配置文件,配置文件放在自己的项目中-->
                        <configFile>./src/main/resources/smart-doc.json</configFile>
                        <!--smart-doc实现自动分析依赖树加载第三方依赖的源码，如果一些框架依赖库加载不到导致报错，这时请使用excludes排除掉-->
                        <excludes>
                            <!--格式为：groupId:artifactId;参考如下-->
                            <!--也可以支持正则式如：com.alibaba:.* -->
                            <exclude>com.alibaba:.*</exclude>
                            <exclude>cn.hutool:hutool-core</exclude>
                        </excludes>
                    </configuration>
                    <executions>
                        <execution>
                            <!--如果不需要在执行编译时启动smart-doc，则将phase注释掉-->
                            <phase>compile</phase>
                            <goals>
                                <!--smart-doc提供了html、openapi、markdown等goal，可按需配置-->
                                <goal>${smart.doc.goal}</goal>
                            </goals>
                        </execution>
                    </executions>
                </plugin>
            </plugins>
        </pluginManagement>

        <plugins>
            <!-- smart-doc插件定义 -->
            <plugin>
                <groupId>com.github.shalousun</groupId>
                <artifactId>smart-doc-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>    
</project>

三、smart-doc.json配置

在src/main/resources下添加smart-doc.json，示例配置如下:

注: 该配置文件smart-doc.json的具体位置可参见前一章节中的maven插件的<configFile/>配置

{
  "projectName": "D3S - Smartdoc - API",
  "serverUrl": "http://localhost:8080",
  "pathPrefix": "/",
  "outPath": "./target/smart-doc",
  "allInOne": true,
  "showAuthor": true,
  "groups": [
    {
      "name": "用户管理",
      "apis": "com.luo.demo.api.controller.user.*"
    },
    {
      "name": "角色管理",
      "apis": "com.luo.demo.api.controller.role.*"
    }
  ],
  "revisionLogs": [
    {
      "version": "1.0",
      "revisionTime": "2022-01-17 16:30",
      "status": "create",
      "author": "luohq",
      "remarks": "Smartdoc OAS3集成Springdoc"
    }
  ]
}

注：
outPath为生成接口文档位置，上述示例配置放到了target/smart-doc下，亦可将文档生成至源代码路径，如: ./src/main/resources/smart-doc，
groups、revisionLogs若不需要可移除，
完整配置说明可参见：https://smart-doc-group.github.io/#/zh-cn/diy/config。

四、smart-doc-maven-plugin相关命令

如上集成方式可直接使用mvn clean package即可生成smart-doc相关接口文档，
在D3S中使用smart-doc生成的OpenAPI接口文档，具体内容可参见：gitee/luoex/d3s/…/doc/openapi
更多smart-doc相关命令使用参考如下：

# =========== REST 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
# 生成 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文档 =============
# 生成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
# 生成dubbo接口文档推送到torna
mvn -Dfile.encoding=UTF-8 smart-doc:torna-rpc

五、推送文档到Torna

注：
关于Torna管理端的搭建可参见：https://gitee.com/durcframework/torna#方式1下载zip本地运行
Torna相关配置说明可参见：https://torna.cn/dev/config.html

修改src/main/resources/smart-doc.json配置，添加appToken、openUrl属性：

{
  "projectName": "D3S smart-doc API",
  "serverUrl": "http://localhost:8080",
  "pathPrefix": "/",
  "outPath": "./src/main/resources/static/doc",
  "allInOne": true,
  //appToken对应下图Tonar管理端中的token
  "appToken": "c16931fa6590483fb7a4e85340fcbfef",
  //openUrl对应下图Tonar管理端中的请求路径
  "openUrl": "http://localhost:7700/api"
}

其中appToken、openUrl对应Torna中具体应用下的配置，
在Torna中的层级分为：空间 -> 项目 -> 应用，
依次创建对应层级后，到具体的应用中的OpenAPI菜单，
如下的token即对应appToken，请求路径即对应openUrl。

在这里插入图片描述

执行如下命令后，即可将smart-doc生成的文档同步到Torna：

# 生成接口文档并推送到Torna平台
mvn -Dfile.encoding=UTF-8 smart-doc:torna-rest

同步到Torna后效果如下：
在这里插入图片描述

六、通过Maven Profile简化构建

在pom中添加不同profile，用于区分smart-doc-maven-plugin构建目标，后续切换不同Profile即可执行对应的目标：

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    
    <properties>
        <smart.doc.version>2.6.1</smart.doc.version>
        <smart.doc.goal>openapi</smart.doc.goal>
    </properties>

    <build>
        <pluginManagement>
            <plugins>
                <!-- smart-doc插件定义 -->
                <plugin>
                    <groupId>com.github.shalousun</groupId>
                    <artifactId>smart-doc-maven-plugin</artifactId>
                    <version>${smart.doc.version}</version>
                    <configuration>
                        <!--指定生成文档的使用的配置文件,配置文件放在自己的项目中-->
                        <configFile>./src/main/resources/smart-doc.json</configFile>
                        <!--smart-doc实现自动分析依赖树加载第三方依赖的源码，如果一些框架依赖库加载不到导致报错，这时请使用excludes排除掉-->
                        <excludes>
                            <!--格式为：groupId:artifactId;参考如下-->
                            <!--也可以支持正则式如：com.alibaba:.* -->
                            <exclude>com.alibaba:.*</exclude>
                            <exclude>cn.hutool:hutool-core</exclude>
                        </excludes>
                    </configuration>
                    <executions>
                        <execution>
                            <!--如果不需要在执行编译时启动smart-doc，则将phase注释掉-->
                            <phase>compile</phase>
                            <goals>
                                <!--smart-doc提供了html、openapi、markdown等goal，可按需配置-->
                                <goal>${smart.doc.goal}</goal>
                            </goals>
                        </execution>
                    </executions>
                </plugin>
            </plugins>
        </pluginManagement>
    </build>

    <profiles>
        <!-- 生成openapi.json -->
        <profile>
            <id>smart-doc-openapi</id>
            <activation>
                <activeByDefault>true</activeByDefault>
            </activation>
            <properties>
                <smart.doc.goal>openapi</smart.doc.goal>
            </properties>
        </profile>

        <!-- 同步到Torna -->
        <profile>
            <id>smart-doc-torna-rest</id>
            <properties>
                <smart.doc.goal>torna-rest</smart.doc.goal>
            </properties>
        </profile>

        <!-- 生成Html接口文档 -->
        <profile>
            <id>smart-doc-html</id>
            <properties>
                <smart.doc.goal>html</smart.doc.goal>
            </properties>
        </profile>

        <!-- 生成Markdown接口文档 -->
        <profile>
            <id>smart-doc-markdown</id>
            <properties>
                <smart.doc.goal>markdown</smart.doc.goal>
            </properties>
        </profile>
    </profiles>

</project>

之后即可通过切换mvn profile生成不同形式的接口文档:

# 生成openapi.json
mvn clean package -P smart-doc-openapi
# 生成html接口文档
mvn clean package -P smart-doc-html
# 生成markdown接口文档
mvn clean package -P smart-doc-markdown
# 推送到Torna
mvn clean package -P smart-doc-torna-rest