smart-doc 使用说明

smart-doc 使用说明

官方使用介绍：smart-doc功能使用介绍 - 上官胡闹的个人空间 - OSCHINA - 中文开源技术交流社区

官方配置介绍：smart-doc-maven-plugin: smart-doc官方maven插件 (gitee.com)

官方wiki：HOME - Wiki - Gitee.com

对于smart-doc，官方是有3种方式的：

• 单元测试生成（不推荐）
• maven插件生成
• gradle插件生成

特殊功能

支持JSR303规范

支持fastjson和Jackson字段注解如：

• @JSONField(serialize = false) – 字段忽略
• @JSONField(name = “create_time”) – 字段名称

请求参数忽略（1.5 + 版本）

/**
     *  创建时间
     *  @ignore
     */
private Timestamp createTime;

参数模拟

它会自动生成一个模拟参数，不用任何配置

文档变更记录

需要在smart-doc.json里增加配置：“allInOne”: true

{
  "outPath": "D://md2",
  "allInOne": true
}

我们也可以自己设置它的一个变更记录，增加这个配置

 "revisionLogs": [{ //设置文档变更记录，没有需求可以不设置
      "version": "1.0", //文档版本号
      "revisionTime": "2020-12-31 10:30", //文档修订时间
      "status": "update", //变更操作状态，一般为：创建、更新等
      "author": "author", //文档变更作者
      "remarks": "desc" //变更描述
  }],

而这个配置，不需要配置"allInOne": true

字段版本记录

使用原生注释：@since

 /**
     * @since 1.0
     * 用户名称
     */
    private String subUserName;

多模块配置

smart-doc之前说过是无侵入，通过注释来生成的API文档，所以对于多模块服务，无法获取到注释，需要获取到源代码才能进行分析，而对于这种情况，smart-doc也有手段解决。

1. ApiConfig配置

ApiConfig config = new ApiConfig();
//以前的版本为setSourcePaths，SourceCodePath为SourcePath
config.setSourceCodePaths(
        SourceCodePath.path().setDesc("本项目代码").setPath("src/main/java"),
        //smart-doc对路径自动会做处理，无论是window合适linux系统路径，直接拷贝贴入即可
        SourceCodePath.path().setDesc("加载外部项目源码").setPath("E:\\Test\\Mybatis-PageHelper-master\\src\\main\\java")
);

根据官网所说，后续版本不需要再手动配置，而这个功能我还没测试，其最终效果不得而见。

2. maven的classifier指定源码包

<!--依赖的库-->
<dependency>
    <groupId>com.github.shalousun</groupId>
    <artifactId>common-util</artifactId>
    <version>[最新版本]</version>
</dependency>
<!--依赖库源码-->
<dependency>
    <groupId>com.github.shalousun</groupId>
    <artifactId>common-util</artifactId>
    <version>[最新版本]</version>
    <classifier>sources</classifier>
    <!--设置为test,项目发布时source不会放入最终的产品包-->
    <scope>test</scope>
</dependency>

而这种方式在打包需要增加一个插件，才能在打包上将源码包打包的仓库

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-source-plugin</artifactId>
    <version>3.1.0</version>
    <executions>
        <execution>
            <phase>package</phase>
            <goals>
                <goal>jar-no-fork</goal>
            </goals>
        </execution>
    </executions>
</plugin>

文档输出

默认我们是配置smart-doc.json的一个配置文件，里面必填参数就是“outPath”，

{
  "outPath": "这里可以写resources下面的路径，在SpringBoot启动后就可以进行访问",
  "allInOne": true
}

路径配置好像不支持相对路径，所以使用绝对路径，但还有一个方法，就是使用代码：

注意这里的postman和HTML只能输出一个

 @org.junit.Test
    public void smartDocApiConfig() {
        ApiConfig config = new ApiConfig();
        //导出postman建议将server设置成这样，然后在postman中建立一个server环境变量，调试时只需根据实际服务器来修改server的值。
        config.setServerUrl("http://{{server}}");

        config.setAllInOne(true);
        // 文档输出路径
        config.setOutPath(System.getProperty("user.dir") + DocGlobalConstants.FILE_SEPARATOR + DocGlobalConstants.HTML_DOC_OUT_PATH);
        // postman JSON输出（1.8+)
//        PostmanJsonBuilder.buildPostmanCollection(config);
        // html 文档输出
        HtmlApiDocBuilder.buildApiDoc(config);
    }

服务配置

spring.resources.add-mappings=false只要配置了这个，就不能访问静态资源了，但如果是对于单体服务，这个配置不能改，所以，可能需要委婉一点处理。

smart-doc自定义注释

ignore注释，上面有提到过

tag名称	描述
@ignore	ignore tag用于过滤请求参数对象上的某个字段，设置后smart-doc不输出改字段到请求参数列表中。
@required	如果你没有使用JSR303参数验证规范实现的方式来标准字段，就可以使用@required去标注请求参数对象的字段，标注smart-doc在输出参数列表时会设置为true。

配置请求参数和详情体包装

 "responseBodyAdvice":{ //自smart-doc 1.9.8起，ResponseBodyAdvice统一返回设置，可用ignoreResponseBodyAdvice tag来忽略
       "className":"com.power.common.model.CommonResult" //通用响应体
  },
  "requestBodyAdvice":{ //自smart-doc 2.1.4 起，支持设置RequestBodyAdvice统一请求包装类
       "className":"com.power.common.model.CommonResult"
  },

smart-doc api如何做接口测试

做测试，smart虽然没有提供，但是，它提供了与其他工具的对接，这点还是不错的，毕竟专业的还是专业的。

1. 导入postman

导入postman需要一个JSON文件，在smart-doc 1.7+ 是支持的。

那么我们在去看看官方的配置说明：

需要使用java代码来构建json:

 @org.junit.Test
    public void smartDocApiConfig() {
        ApiConfig config = new ApiConfig();
        //导出postman建议将server设置成这样，然后在postman中建立一个server环境变量，调试时只需根据实际服务器来修改server的值。
        config.setServerUrl("http://{{server}}");

        config.setAllInOne(true);
        // 文档输出路径
        config.setOutPath(System.getProperty("user.dir") + DocGlobalConstants.FILE_SEPARATOR + DocGlobalConstants.HTML_DOC_OUT_PATH);
        // postman JSON输出（1.8+)
        PostmanJsonBuilder.buildPostmanCollection(config);
        // html 文档输出
//        HtmlApiDocBuilder.buildApiDoc(config);
    }

将生成的JSON文件导入postman，进行测试。

1. 在smart-doc里我们配置了http://{{server}}，这个server是作为postman中的环境变量

2. 在postman中，点击右上角配置，或是在左上角的new都可以新建环境变量

   

3. 到这基本已经可以了，如果要做到自动化测试，还需要配各种变量和脚本，但根据现在的情况已经够用了。需要详细的可以到网上查看相关配置和语法。

2.对接torna

torna属于开源项目，需要下载部署

部署

部署方式可以是jar部署，和docker部署，详细的步骤在：torna使用步骤

对于现在的项目完全使用jar包方式的没问题，毕竟都要下载。

1. 导入数据库，复制官方的mysql.sql

   mysql -u root -p

   source ./mysql.sql

2. 修改application.properties，mysql的连接

3. 运行startup.sh

登录

1. torna超级管理员登录

   admin@torna.cn/123456
   

   

   API文档支持swagger和postman

   

   

   对接

   最后重点的一步来了，创建key

   对接需要3个key：

   • AppKey和secret

     空间列表，选择一个空间

   

   

   • AppToken

   这个需要进入项目，然后创建一个模块，然后找到openApi

   

smart-doc对接

只需要配置一些配置就行

{
  "outPath": "D://md2",
//  "allInOne": true,

  "serverUrl": "http://{{server}}",
  "revisionLogs": [{ //设置文档变更记录，没有需求可以不设置
    "version": "1.0", //文档版本号
    "revisionTime": "2020-12-31 10:30", //文档修订时间
    "status": "update", //变更操作状态，一般为：创建、更新等
    "author": "author", //文档变更作者
    "remarks": "desc" //变更描述
  }],
  "isStrict": false, //是否开启严格模式
//  "packageFilters": "",//controller包过滤，多个包用英文逗号隔开
  "projectName": "smart-doc",//配置自己的项目名称
  "appKey": "20210523846044457521381376",// torna平台对接appKey,, @since 2.0.9
  "appToken": "a3f747cf83b94eb7927abd1e578fc87c", //torna平台appToken,@since 2.0.9
  "secret": "TDZQFAb*n7aAwY,M6#V68PO3BcobQTGY",//torna平台secret，@since 2.0.9
  "openUrl": "http://localhost:7700/api",//torna平台地址，填写自己的私有化部署地址@since 2.0.9
  "debugEnvName":"test", //torna测试环境
  "debugEnvUrl":"http://127.0.0.1"//torna
}