定制企业网站软文范例

一、引言

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