首页
学习
活动
专区
工具
TVP
发布
社区首页 >专栏 >smart-doc 使用说明

smart-doc 使用说明

作者头像
用针戳左手中指指头
发布2021-09-10 10:57:43
3.2K0
发布2021-09-10 10:57:43
举报
文章被收录于专栏:学习计划学习计划

文章目录

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都可以新建环境变量
image-20210523142954993
image-20210523142954993
  1. 到这基本已经可以了,如果要做到自动化测试,还需要配各种变量和脚本,但根据现在的情况已经够用了。需要详细的可以到网上查看相关配置和语法。

2.对接torna

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

部署

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

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

  1. 导入数据库,复制官方的mysql.sql mysql -u root -p source ./mysql.sql
  2. 修改application.properties,mysql的连接
  3. 运行startup.sh

登录

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
image-20210523154549367
本文参与 腾讯云自媒体分享计划,分享自作者个人站点/博客。
原始发表:2021-07-17 ,如有侵权请联系 cloudcommunity@tencent.com 删除

本文分享自 作者个人站点/博客 前往查看

如有侵权,请联系 cloudcommunity@tencent.com 删除。

本文参与 腾讯云自媒体分享计划  ,欢迎热爱写作的你一起参与!

评论
登录后参与评论
0 条评论
热度
最新
推荐阅读
目录
  • 文章目录
  • smart-doc 使用说明
    • 特殊功能
      • 支持JSR303规范
      • 支持fastjson和Jackson字段注解如:
      • 请求参数忽略(1.5 + 版本)
      • 参数模拟
      • 文档变更记录
      • 字段版本记录
    • 多模块配置
      • 1. ApiConfig配置
      • 2. maven的classifier指定源码包
    • 文档输出
      • 服务配置
        • smart-doc自定义注释
          • 配置请求参数和详情体包装
          • smart-doc api如何做接口测试
            • 1. 导入postman
              • 2.对接torna
                • 部署
                • 登录
                • smart-doc对接
            相关产品与服务
            容器服务
            腾讯云容器服务(Tencent Kubernetes Engine, TKE)基于原生 kubernetes 提供以容器为核心的、高度可扩展的高性能容器管理服务,覆盖 Serverless、边缘计算、分布式云等多种业务部署场景,业内首创单个集群兼容多种计算节点的容器资源管理模式。同时产品作为云原生 Finops 领先布道者,主导开源项目Crane,全面助力客户实现资源优化、成本控制。
            领券
            问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档