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

目录

    • 一、引言
    • 二、maven插件
    • 三、smart-doc.json配置
    • 四、smart-doc-maven-plugin相关命令
    • 五、推送文档到Torna
    • 六、通过Maven Profile简化构建

一、引言

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

本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若转载，请注明出处：http://www.hqwc.cn/news/66064.html

如若内容造成侵权/违法违规/事实不符，请联系编程知识网进行投诉反馈email:809451989@qq.com，一经查实，立即删除！

相关文章

TCP/IP 下的计算机网络江湖

TCP/IP 下的计算机网络江湖

〇、引言 在当今数字化时代，计算机网络宛如广袤江湖，涵盖着五大门派：物理层、数据链路层、网络层、传输层和应用层。每个门派独具技能，共同构筑着现代网络的框架。物理层宛如江湖基石，将比特流传输；数据链路层如武林传承，组织数据帧传递；网络层则像导航大师，寻找传送路…
阅读更多...
js的练习

js的练习

这里写目录标题 工具代码运行结果 工具 HBuilder X 代码 <!DOCTYPE html> <html><head><meta charset"utf-8"><title></title><script>window.onload function() // 需要在body加载完成之后&#xff0c;才能通过docu…
阅读更多...
立秋至 | 共建智慧城，秋日硕果时

立秋至 | 共建智慧城，秋日硕果时

一缕缕阳光洒向大地 一股股热浪迎面拂来 一声声虫鸣清脆悦耳 一片片黄叶轻声而落 一份份清凉沁入心间 一个个硕果接踵而至 跟随我们一起来回顾下 往期铭控小伙伴们 在助力建设智慧城市 做了哪些努力呢 都做了哪些项目呢 得到了多少客户的认可呢 Part 1 智慧消防 消防…
阅读更多...
LVS简介及LVS-DR搭建

LVS简介及LVS-DR搭建

目录 一. LVS简介&#xff1a; 1.简介 2. LVS工作模式&#xff1a; 3. LVS调度算法&#xff1a; 4. LVS-DR集群介绍&#xff1a; 二.LVS-DR搭建 1.RS配置 1&#xff09;两台RS&#xff0c;需要下载好httpd软件并准备好配置文件 2&#xff09;添加虚拟IP&#xff08;vip&…
阅读更多...
算法通过村第三关-数组青铜笔记|单调数组

算法通过村第三关-数组青铜笔记|单调数组

文章目录 前言单调数组问题搜索插入位置&#xff1a;数组合并问题&#xff1a;总结 前言 提示&#xff1a;本份真诚面对自己、坦然无碍面对他人&#xff0c;就是优雅。 数组中的比较经典性问题: 单调数组问题数组合并问题 单调数组问题 参考例子&#xff1a;896. 单调数列…
阅读更多...
16.2.3 【Linux】离线管理问题

16.2.3 【Linux】离线管理问题

要注意的是&#xff0c;我们在工作管理当中提到的“背景”指的是在终端机模式下可以避免 [crtl]-c 中断的一个情境&#xff0c; 你可以说那个是 bash 的背景&#xff0c;并不是放到系统的背景去。所以&#xff0c;工作管理的背景依旧与终端机有关。在这样的情况下&#xff0c;如…
阅读更多...
RabbitMQ：可靠消息传递的强大消息中间件

RabbitMQ：可靠消息传递的强大消息中间件

消息中间件在现代分布式系统中起着关键作用&#xff0c;它们提供了一种可靠且高效的方法来进行异步通信和解耦。在这篇博客中&#xff0c;我们将重点介绍 RabbitMQ&#xff0c;一个广泛使用的开源消息中间件。我们将深入探讨 RabbitMQ 的特性、工作原理以及如何在应用程序中使用…
阅读更多...
Spring(13) IOC的工作流程

Spring(13) IOC的工作流程

目录 一、定义二、Bean的声明方式三、IOC的工作流程 一、定义 IOC&#xff1a;全称是 Inversion Of Control&#xff0c;也就是控制反转&#xff0c;它的核心思想是把对象的管理权限交给容器。应用程序如果需要使用某个对象的实例&#xff0c;那么直接从 IOC 容器里面去获取就…
阅读更多...
在 Windows 中恢复数据的 5 种方法

在 Windows 中恢复数据的 5 种方法

发生数据丢失的原因有多种。无论是因为文件被意外删除、文件系统或操作系统损坏&#xff0c;还是由于软件或硬件级别的存储故障&#xff0c;数据都会在您最意想不到的时候丢失。今天我们重点介绍五种数据恢复方法&#xff0c;以应对意外情况的发生。 1.从另一台机器启动硬盘 如…
阅读更多...
gitee linux免密/SSH 方式连接免登录

gitee linux免密/SSH 方式连接免登录

目录 账号密码方式免登录&#xff08;不推荐&#xff09;添加git配置新建保存密码文件git clone SSH 方式连接免登录&#xff08;推荐&#xff09;生成SSH公钥通过 ssh-keygen 程序创建找到SSH公钥 在gitee中添加公钥git clone 参考 账号密码方式免登录&#xff08;不推荐&…
阅读更多...
Mysql主从分离

Mysql主从分离

一、前言 某个应用场景中&#xff0c;在操作数据库这部分&#xff0c;往往是数据库的读取往往大于数据库的写入&#xff0c;当读取数据达到数据库的瓶颈时&#xff0c;性能下滑&#xff0c;影响数据的写入&#xff0c;导致整个应用的不可用。为了解决这个问题&#xff0c;这时&…
阅读更多...
【设计模式】MVC 模式

【设计模式】MVC 模式

MVC 模式代表 Model-View-Controller&#xff08;模型-视图-控制器&#xff09; 模式。这种模式用于应用程序的分层开发。 Model&#xff08;模型&#xff09; - 模型代表一个存取数据的对象或 JAVA POJO。它也可以带有逻辑&#xff0c;在数据变化时更新控制器。View&#xff…
阅读更多...
推荐文章
最新文章

Copyright @ 2022~2023