dede 网站内页标题修改,网站建设外包发展情况,qq代挂主站网站建设,设计参考网站推荐目录 一、引言二、maven插件三、smart-doc.json配置四、smart-doc-maven-plugin相关命令五、推送文档到Torna六、通过Maven Profile简化构建 一、引言
D3S#xff08;DDD with SpringBoot#xff09;为本作者使用DDD过程中开发的框架#xff0c;目前已可公开查看源码#… 目录 一、引言二、maven插件三、smart-doc.json配置四、smart-doc-maven-plugin相关命令五、推送文档到Torna六、通过Maven Profile简化构建 一、引言
D3SDDD 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 version1.0 encodingUTF-8?
project xmlnshttp://maven.apache.org/POM/4.0.0 xmlns:xsihttp://www.w3.org/2001/XMLSchema-instancexsi:schemaLocationhttp://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsdpropertiessmart.doc.version2.6.1/smart.doc.versionsmart.doc.goalopenapi/smart.doc.goal/propertiesbuildpluginManagementplugins!-- smart-doc插件定义 --plugingroupIdcom.github.shalousun/groupIdartifactIdsmart-doc-maven-plugin/artifactIdversion${smart.doc.version}/versionconfiguration!--指定生成文档的使用的配置文件,配置文件放在自己的项目中--configFile./src/main/resources/smart-doc.json/configFile!--smart-doc实现自动分析依赖树加载第三方依赖的源码如果一些框架依赖库加载不到导致报错这时请使用excludes排除掉--excludes!--格式为groupId:artifactId;参考如下--!--也可以支持正则式如com.alibaba:.* --excludecom.alibaba:.*/excludeexcludecn.hutool:hutool-core/exclude/excludes/configurationexecutionsexecution!--如果不需要在执行编译时启动smart-doc则将phase注释掉--phasecompile/phasegoals!--smart-doc提供了html、openapi、markdown等goal可按需配置--goal${smart.doc.goal}/goal/goals/execution/executions/plugin/plugins/pluginManagementplugins!-- smart-doc插件定义 --plugingroupIdcom.github.shalousun/groupIdartifactIdsmart-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.encodingUTF-8 smart-doc:html
# 生成markdown
mvn -Dfile.encodingUTF-8 smart-doc:markdown
# 生成adoc
mvn -Dfile.encodingUTF-8 smart-doc:adoc
# 生成postman json数据
mvn -Dfile.encodingUTF-8 smart-doc:postman
# 生成 Open Api 3.0,Since smart-doc-maven-plugin 1.1.5
mvn -Dfile.encodingUTF-8 smart-doc:openapi
# 生成文档推送到Torna平台
mvn -Dfile.encodingUTF-8 smart-doc:torna-rest# Apache Dubbo RPC文档
# 生成html
mvn -Dfile.encodingUTF-8 smart-doc:rpc-html
# 生成markdown
mvn -Dfile.encodingUTF-8 smart-doc:rpc-markdown
# 生成adoc
mvn -Dfile.encodingUTF-8 smart-doc:rpc-adoc
# 生成dubbo接口文档推送到torna
mvn -Dfile.encodingUTF-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管理端中的tokenappToken: c16931fa6590483fb7a4e85340fcbfef,//openUrl对应下图Tonar管理端中的请求路径openUrl: http://localhost:7700/api
}其中appToken、openUrl对应Torna中具体应用下的配置 在Torna中的层级分为空间 - 项目 - 应用 依次创建对应层级后到具体的应用中的OpenAPI菜单 如下的token即对应appToken请求路径即对应openUrl。 执行如下命令后即可将smart-doc生成的文档同步到Torna
# 生成接口文档并推送到Torna平台
mvn -Dfile.encodingUTF-8 smart-doc:torna-rest同步到Torna后效果如下
六、通过Maven Profile简化构建
在pom中添加不同profile用于区分smart-doc-maven-plugin构建目标后续切换不同Profile即可执行对应的目标
?xml version1.0 encodingUTF-8?
project xmlnshttp://maven.apache.org/POM/4.0.0 xmlns:xsihttp://www.w3.org/2001/XMLSchema-instancexsi:schemaLocationhttp://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsdpropertiessmart.doc.version2.6.1/smart.doc.versionsmart.doc.goalopenapi/smart.doc.goal/propertiesbuildpluginManagementplugins!-- smart-doc插件定义 --plugingroupIdcom.github.shalousun/groupIdartifactIdsmart-doc-maven-plugin/artifactIdversion${smart.doc.version}/versionconfiguration!--指定生成文档的使用的配置文件,配置文件放在自己的项目中--configFile./src/main/resources/smart-doc.json/configFile!--smart-doc实现自动分析依赖树加载第三方依赖的源码如果一些框架依赖库加载不到导致报错这时请使用excludes排除掉--excludes!--格式为groupId:artifactId;参考如下--!--也可以支持正则式如com.alibaba:.* --excludecom.alibaba:.*/excludeexcludecn.hutool:hutool-core/exclude/excludes/configurationexecutionsexecution!--如果不需要在执行编译时启动smart-doc则将phase注释掉--phasecompile/phasegoals!--smart-doc提供了html、openapi、markdown等goal可按需配置--goal${smart.doc.goal}/goal/goals/execution/executions/plugin/plugins/pluginManagement/buildprofiles!-- 生成openapi.json --profileidsmart-doc-openapi/idactivationactiveByDefaulttrue/activeByDefault/activationpropertiessmart.doc.goalopenapi/smart.doc.goal/properties/profile!-- 同步到Torna --profileidsmart-doc-torna-rest/idpropertiessmart.doc.goaltorna-rest/smart.doc.goal/properties/profile!-- 生成Html接口文档 --profileidsmart-doc-html/idpropertiessmart.doc.goalhtml/smart.doc.goal/properties/profile!-- 生成Markdown接口文档 --profileidsmart-doc-markdown/idpropertiessmart.doc.goalmarkdown/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
