简介
smart-doc
完全基于接口源码来分析生成接口文档,不采用任何注解侵入到业务代码中。你只需要按照Javadoc
标准编写注释, smart-doc
就能帮你生成一个简易明了的Markdown
、HTML5
、Postman
Collection2.0+
、OpenAPI 3.0+
的文档。
smart-doc
(文档生成) + Torna
(文档管理)可以实现接口文档自动化,替换Apifox
smart-doc功能
:
- 生成接口离线文档(html, markdown, openapi等)
- 推送接口到Torna在线管理
gitee:
smart-doc: smart-doc是一款同时支持java restful api和apache dubbo rpc接口文档生成的工具。完全基于注释生成文档,做到零侵入。 (gitee.com)
使用
简介 (smart-doc-group.github.io)
smart-doc maven插件
安装
maven多模块项目结构
其中dubbo-provider
, spring-boot-web1
, spring-boot-web2
为各服务启动模块
spring-boot-maven-multiple-module
├── common
│ ├── pom.xml
├── dubbo-api
│ ├── pom.xml
├── dubbo-provider
│ ├── pom.xml
│ └── src
│ ├── main
│ │ ├── java
│ │ │ └── com
│ │ └── resources
│ │ ├── application.yml
│ │ ├── smart-doc.json
├── module2
│ └── pom.xml
├── spring-boot-web1
│ ├── pom.xml
│ └── src
│ └── main
│ ├── java
│ │ └── com
│ └── resources
│ ├── application.yml
│ ├── smart-doc.json
├── spring-boot-web2
│ ├── pom.xml
│ └── src
│ └── main
│ ├── java
│ │ └── com
│ └── resources
│ ├── application.yml
│ ├── smart-doc.json
├── pom.xml
主工程spring-boot-maven-multiple-module
的pom.xml
中定义插件配置管理
插件配置管理<pluginManagement>仅做配置,并不生效
smart-doc-maven-plugin
maven-source-plugin
<build>
<pluginManagement>
<plugins>
<!-- smart-doc插件 -->
<plugin>
<groupId>com.github.shalousun</groupId>
<artifactId>smart-doc-maven-plugin</artifactId>
<version>2.4.9</version>
<configuration>
<!--指定生成文档的使用的配置文件-->
<configFile>${basedir}/src/main/resources/smart-doc.json</configFile>
<!--指定项目名称-->
<projectName>商城项目</projectName>
</configuration>
<executions>
<execution>
<phase>package</phase>
<goals>
<!--smart-doc提供了html、openapi、markdown等goal,可按需配置-->
<goal>html</goal>
<goal>openapi</goal>
<goal>markdown</goal>
</goals>
</execution>
</executions>
</plugin>
<plugin>
<!-- 打包源码 -->
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-source-plugin</artifactId>
<version>3.2.1</version>
<executions>
<execution>
<id>attach-sources</id>
<goals>
<!--<goal>jar</goal>-->
<goal>jar-no-fork</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</pluginManagement>
</build>
启动服务添加smart-doc插件
由于插件的version, execution等信息已经在主工程工程spring-boot-maven-multiple-module
的pom.xml
中配置过了,这里直接使用即可。
dubbo-provider
, spring-boot-web1
, spring-boot-web2
工程的pom.xml分别添加如下插件。
PS: smart-doc的原理是扫描源码文件,然后解析注释,因此必须确保有源码。maven-source-plugin
插件帮我们打包源码到target/xxx-1.0-SNAPSHOT-sources.jar
<build>
<plugins>
<!-- 打包源码 -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-source-plugin</artifactId>
</plugin>
<!-- smart-doc插件 -->
<plugin>
<groupId>com.github.shalousun</groupId>
<artifactId>smart-doc-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
maven打包
mvn install将maven工程打包到本地仓库
配置Torna上传地址和token
Torna平台里获取地址
maven resources/目录下新增smart-doc.json
-
outPath : smart-doc生成的html,markdown等文件的地址
-
projectName : smart-doc生成的html,markdown等文件里面的项目名
-
packageFilters : 扫描的接口package路径
-
openUrl : Torna上传接口地址
-
appToken : Torna上传token
-
debugEnvName : 接口测试环境名,会在Torna里面新增环境
-
debugEnvUrl : 接口测试环境url,会在Torna里面新增环境
-
tornaDebug : 是否开启测试
-
replace : 是否替换已存在接口文档
{
“outPath”: “target/doc”,
“projectName”: “测试smart-doc”,
“packageFilters”: “com.chery.foxlogrecord.demo.controller.*”,
“openUrl”: “http://localhost:7700/api”,
“appToken”: “270c902cb205421f92f20bcxxxxxx”,
“debugEnvName”:“dev”,
“debugEnvUrl”:“http://127.0.0.1:8080”,
“tornaDebug”: true,
“replace”: true
}
上传接口到Torna
方式一:
cmd命令行执行mvn -Dfile.encoding=UTF-8 smart-doc:torna-rest -pl :spring-boot-web1 -am
其中-pl: {maven工程名}
方式二:
IDEA内双击smart-doc:torna-rest
smart-doc生成html, openapi, markdown等文件
IDEA内双击即可,会生成在smart-doc.json里配置的outPath目录
smart-doc推送swagger注解的接口到Torna
smart-doc的maven插件是使用javadoc生成接口文档(不识别swagger注解),如果想要将swagger注解接口推送到Torna,可以使用如下方式:
pom.xml引入swagger-plugin
<dependency>
<groupId>cn.torna</groupId>
<artifactId>swagger-plugin</artifactId>
<version>1.2.24</version>
<scope>test</scope>
</dependency>
resources/目录新增配置文件torna.json
注意scanApis必填
{
"enable": true,
"basePackage": "com.chery.foxlogrecord.demo.controller",
"scanApis": [
"com.chery.foxlogrecord.demo.controller.OperationController"
],
"url": "http://localhost:7700/api",
"token": "270c902cb205421f92f20bcxxxx",
"debugEnv": "dev,http://127.0.0.1:8080",
"author": "Tom",
"debug": true,
"isReplace": true
}
注释详解
{
// 开启推送
"enable": true,
// 扫描package,多个用;隔开
"basePackage": "cn.torna.tornaexample.controller",
// 扫描指定的controller或方法,更细粒度的推送,比如只推送某个接口
"scanApis": [
// 只推送Example20211110Controller类中的接口
//"cn.torna.tornaexample.controller.p202111.Example20211110Controller",
// 只推送某一个接口
//"cn.torna.tornaexample.controller.product.Example2021922Controller.delete"
],
// 推送URL,IP端口对应Torna服务器
"url": "http://localhost:7700/api",
// 模块token
"token": "78488946f9494242bb079f3acba907a6",
// 调试环境,格式:环境名称,调试路径,多个用"|"隔开
"debugEnv": "local,http://127.0.0.1:8088",
// 推送人
"author": "Tom",
// 打开调试:true/false
"debug": true,
// 是否替换文档,true:替换,false:不替换(追加)。默认:true
"isReplace": true,
// ↑↑↑↑↑↑↑↑ 以上为必填项 ↑↑↑↑↑↑↑↑
// 第三方jar中的class配置
"jarClass": {
"com.baomidou.mybatisplus.extension.plugins.pagination.Page": {
"records": { "value": "查询数据列表", "example": "" },
"total": { "value": "总数", "example": "100" },
"size": { "value": "页数", "example": "10" },
"current": { "value": "当前页", "example": "1" },
"countId": { "hidden": true },
"orders": { "hidden": true }
}
},
// 定义全局错误码,也可以定义枚举
"codes": [
// 每一项表示一个分组
// 定义错误码
{
"name": "错误码", // 分组名称
"description": "这里是全局错误码", // 错误码描述
"itemType": "string", // 错误码类型
"items": [
{ "value": "W_10001", "description": "参数错误" },
{ "value": "W_10002", "description": "缺少token" },
{ "value": 10000, "type": "number", "description": "缺少参数" } // 单独指定类型
]
},
// 定义枚举
{
"name": "订单状态枚举",
"itemType": "number",
"items": [
{ "name": "WAIT_PAY", "value": 0, "description": "未支付" },
{ "name": "HAS_PAY", "value": 1, "description": "已支付" },
{ "name": "CANCEL", "value": 2, "description": "取消支付" }
]
},
{
"name": "用户状态",
"itemType": "number",
"items": [
{ "name": "ENABLE", "value": 1, "description": "启用" },
{ "name": "DISABLE", "value": 0, "description": "禁用" }
]
}
],
// 只能是object类型对象
"objectClassList": [
"cn.hutool.json.JSONObject",
"com.alibaba.fastjson.JSONObject"
]
}
编写单元测试
package com.chery.foxlogrecord.demo.controller;
import cn.torna.swaggerplugin.SwaggerPlugin;
import lombok.extern.slf4j.Slf4j;
import org.junit.jupiter.api.Test;
import org.springframework.boot.test.context.SpringBootTest;
@Slf4j
@SpringBootTest
public class SmartDocTest {
@Test
public void push() {
SwaggerPlugin.pushDoc();
// 默认查找resources下的torna.json
// 可复制一份用来区分不同环境,然后参数传文件名称
//SwaggerPlugin.pushDoc("torna-test.json");
}
}
Javadoc注释
参考官网说明即可使用指南 (smart-doc-group.github.io)
补充说明:
- @ignore:忽略controller, 方法,参数等
- @mock:接口文档的示例值(很实用)
- JSR参数验证:控制参数是否必传