简介

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参数验证：控制参数是否必传
# java
Logo
2048 AI社区

有“AI”的1024 = 2048，欢迎大家加入2048 AI社区

更多推荐

构建AI Agent的知识更新机制：保持信息时效性

随着人工智能技术的不断发展，AI Agent在各个领域的应用越来越广泛。然而，知识的时效性对于AI Agent的性能和决策质量至关重要。本文章的目的在于深入探讨如何构建AI Agent的知识更新机制，以确保其能够及时获取和处理最新的信息。范围涵盖了从核心概念的理解到实际项目的应用，以及相关工具和资源的推荐。本文将按照以下结构进行阐述：首先介绍核心概念与联系，让读者对AI Agent和知识更新机制有

avatar 2048 AI社区
cover

OpenClaw 保姆级超详细教程：小白也能轻松上手的 AI 智能体

avatar 2048 AI社区
cover

LLM Agent Scaling瓶颈详解（非常详细），AI智能体协作从入门到精通，收藏这一篇就够了！

avatar 2048 AI社区