手写文档到凌晨？Smart-Doc+Torna 让API文档自动化交付，效率提升300%一直用Swagger作为前后端交

背景

之前一直用Swagger作为前后端交互的接口文档，但是此方案入侵性太强要写一堆注解，UI界面也不是很好看，于是自己一直在苦于寻找一款无侵入性的插件，无意中看到了同城旅行开源的Smart-Doc，使用了一下这就是我想要的啊。

介绍Smart-Doc

引用官网的一段话：Smart-Doc是一款强大的基于Java的API文档生成工具。它通过对接口源代码进行分析来生成全面而准确的文档，完全不需要对代码进行任何注入。这种非侵入式的方法确保了无需添加特殊注解或修改代码即可生成文档，使得集成变得无缝且简单。

集成步骤

请保证你的代码格式符合最佳实践中的格式规范

在项目启动类所在模块的resources目录下创建smart-doc.json文件.

json

{
    "outPath": "/path/to/userdir"
}

outPath也可以使用相对路径, 如: ./src/main/resources/static/doc, 更多配置项请参考配置项

在项目启动类所在模块的pom.xml文件配置Maven插件

TIP

注意: 需要includes依赖的源码包

<plugin>
    <groupId>com.ly.smart-doc</groupId>
    <artifactId>smart-doc-maven-plugin</artifactId>
    <version>[最新版本]</version>
    <configuration> 
        <configFile>./src/main/resources/smart-doc.json</configFile>  
        <projectName>${project.description}</projectName>  
        <includes>  
            <!-- 使用了mybatis-plus的Page分页需要include所使用的源码包 -->
            <include>com.baomidou:mybatis-plus-extension</include>
            <!-- 使用了mybatis-plus的IPage分页需要include mybatis-plus-core-->
            <include>com.baomidou:mybatis-plus-core</include>
            <!-- 使用了jpa的分页需要include所使用的源码包 -->
            <include>org.springframework.data:spring-data-commons</include>             
        </includes> 
    </configuration>
    <executions>
        <execution>
            <!--如果不需要在执行编译时启动smart-doc，则将phase注释掉-->
            <phase>compile</phase>
            <goals>
                <!--smart-doc提供了html、openapi、markdown等goal，可按需配置-->
                <goal>html</goal>
            </goals>
        </execution>
    </executions>
</plugin>

includes中需要调整为项目模块所依赖的包配置groupId:artifactId, 支持正则artifactId:*
phase默认为compile，如果不需要在执行项目编译时启动smart-doc，则将phase注释掉

如果项目依赖其他内部公共模块和第三方包, 则使用maven-source-plugin插件生成源码包上传到内部私服中。 smart-doc自动根据依赖树自动下载源码包，然后进行文档生成。

xml

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-source-plugin</artifactId>
    <version>3.3.1</version>
    <executions>
        <execution>
            <phase>package</phase>
            <goals>
                <goal>jar-no-fork</goal>
            </goals>
            <configuration>
                <encoding>UTF-8</encoding>
            </configuration>
        </execution>
    </executions>
</plugin>

如何使用

在IDEA中直接使用Maven插件目录下的smart-doc模块
在命令行中执行

mvn -Dfile.encoding=UTF-8 smart-doc:html
mvn -Dfile.encoding=UTF-8 smart-doc:markdown
mvn -Dfile.encoding=UTF-8 smart-doc:torna-rest

配置文件讲解

{
  //指定后端服务访问地址,
  "serverUrl": "http://192.168.1.140:8078",
  //指定文档的输出路径，生成到项目静态文件目录下，随项目启动可以查看,
  "outPath": "src/main/resources/static/doc",
  //是否开启严格模式,
  "isStrict": false,
  //是否将文档合并到一个文件中,
  "allInOne": true,
  //是否创建可以测试的html页面,
  "createDebugPage": true,
  //controller包过滤（换成你的路径）, 只有配置的类输出接口文档支持通配符
  "packageFilters": "com.hxy.site.controller.*",
  //基于highlight.js的代码高设置,
  "style": "xt256",
  //配置自己的项目名称,
  "projectName": "测试接口文档",
  //是否显示接口作者名称,
  "showAuthor": false,
  //自定义设置输出文档名称,
  "allInOneDocFileName": "index.html",
  "appToken": "9b82bf84ad814add8b32224f40c705c6", //torna平台appToken,@since 2.0.9
  "openUrl": "http://192.168.200.129:7700/api",//torna平台地址，填写自己的私有化部署地址@since 2.0.9
  "debugEnvName":"测试环境", //torna测试环境
  "replace": true,//推送torna时替换旧的文档
  "debugEnvUrl":"http://192.168.1.140:8078",//torna
  //文档变更记录，非必须,
  "revisionLogs": [
    {
      //文档版本号,
      "version": "1.0",
      //文档修订时间,
      "revisionTime": "2025-06-25 10:30",
      //变更操作状态，一般为：创建、更新等,
      "status": "add",
      //文档变更作者,
      "author": "qmc",
      //变更描述,
      "remarks": "创建文档"
    }
  ],
  // 公共请求参数配置
  "requestHeaders": [
    {
      "name": "Authorization",
      "type": "string",
      "desc": "请求所有接口公共参数",
      "value": "aabcdefasdlf",
      "required": true,
      "excludePathPatterns": "/login,/captchaImage,/site/apply/captcha,/site/apply/captcha/check,/site/apply/submit"
    }
  ],
  // 第三方jar响应实体类字段配置
  "customResponseFields": [
    {
      "name": "id",
      "desc": "验证码id",
      "ownerClassName": "cloud.tianai.captcha.application.vo.CaptchaResponse"
    },
    {
      "name": "captcha",
      "desc": "验证码内容",
      "ownerClassName": "cloud.tianai.captcha.application.vo.CaptchaResponse"
    }
  ]
}