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名称描述
@ignoreignore 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都可以新建环境变量

    image-20210523142954993

  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
    

    image-20210523151450918

    API文档支持swagger和postman

    image-20210523151544429

    image-20210523151637751

    对接

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

    对接需要3个key:

    • AppKey和secret

      空间列表,选择一个空间

    image-20210523151859970

    image-20210523151921563

    • AppToken

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

    image-20210523153125889

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
}

image-20210523154549367

  • 1
    点赞
  • 7
    收藏
  • 打赏
    打赏
  • 3
    评论

“相关推荐”对你有帮助么?

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
©️2022 CSDN 皮肤主题:数字20 设计师:CSDN官方博客 返回首页
评论 3

打赏作者

用针戳左手中指指头

你的鼓励将是我创作的最大动力

¥2 ¥4 ¥6 ¥10 ¥20
输入1-500的整数
余额支付 (余额:-- )
扫码支付
扫码支付:¥2
获取中
扫码支付

您的余额不足,请更换扫码支付或充值

打赏作者

实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、C币套餐、付费专栏及课程。

余额充值