java 交接文档 模版 java项目交接文档

1.对接smart-doc
1.1需要生成的模块pom添加插件

<plugin>
        <groupId>com.github.shalousun</groupId>
        <artifactId>smart-doc-maven-plugin</artifactId>
        <version>2.2.4</version>
        <configuration>
          <configFile>./src/main/resources/smart-doc.json</configFile>
          <projectName>测试</projectName>
          <excludes>
            <exclude>com.alibaba:fastjson</exclude>
          </excludes>
          <includes>
            <include>com.alibaba:fastjson</include>
          </includes>
        </configuration>
        <executions>
          <execution>
            <phase>compile</phase>
            <goals>
              <goal>html</goal>
            </goals>
          </execution>
        </executions>
      </plugin>

1.2 在项目的 resources 包里加入 smart-doc.json
smart初始设置如下

{
  "serverUrl": "http://127.0.0.1:8081",
  "packageFilters": "com.xn.apiController.*", // 配置选择要生成的Controller包
  "isStrict": false,
  "allInOne": true,
  "outPath": "src/main/resources/static/doc",
  "projectName": "smart-doc"
}

1.3执行maven里面的snart-doc插件

1.4成功的话会生成相关的html页面，不成功可能是环境报错，或者有些controller不能识别，可以暂时删除这个controller跟或重新打包项目

1.5右键debug-all.html 再浏览器打开这里页面(这个需要实现跨域)，也可以用当前地址 + 访问静态文件的方式（如：localhost:8081/doc/debug-all.html）可以得到生成的接口文档

2.接入 smart-doc + Torna 实现接口文档自动化

Torna（gitee）

2.1 下载torna

2.2在本地解压后 在application.properties修改对于数据库地址

2.3 启动先在对应的数据库里导入数据

2.4 执行sh startup.sh启动（Windows执行startup.bat）2.5启动后访问 localhost:7700

超级管理员：[e-mail]

密码均为：123456

里面有一些初始数据跟初始用户，不用可以删除2.6 创建 appKey,appToken,secret，只有管理员可以创建

去项目列表创建项目

在通过1,2，3找到相关的token

2.7 配置smart-doc.json文件

{
  "serverUrl": "http://127.0.0.1:8081",
  "isStrict": false,
  "allInOne": true,
  "coverOld": true,
  "packageFilters": "com.xn.apiController.*", // 配置选择要生成的Controller包
  "outPath": "src/main/resources/static/doc",
  "style":"atelier-dune-light", // 高亮
  "createDebugPage": true,
  "style":"xt256",
  "projectName": "API接口文档",
  "errorCodeDictionaries": [{
    "title": "title",
    "enumClassName": "com.xn.respcode.ResponseCode",
    "codeField": "code",
    "descField": "desc"
  }],
  "appKey": "20210902883022958639972352",
  "appToken": "d06e8f3345a1476e8c977d8b92840162",
  "secret": "FSbdo>Dur.9!3qhh2^q$Y5wUfP2gssan",
  "openUrl": "http://localhost:7700/api",
  "debugEnvName":"小程序端Api",
  "debugEnvUrl":"http://127.0.0.1:8081"
}

2.8执行maven里面的snart-doc插件

执行成功后会生成新的接口文档，直接访问刚才文件配置的地址 http://localhost:7700

文档会生成在你配置key,token 的空间里面。

3关于torna 的注释格式

调试发现，在controller上改注释，会重新生成一个新的接口文档，以前的也不会覆盖，只能通过删除doc_info表里面的数据或者手动删除才可以，还好修改接口的注释不会。