【Smart-Doc】使用说明

Forget_G

已于 2022-12-03 16:59:34 修改

阅读量4.2k

点赞数 1

文章标签： java 开源测试工具

于 2022-12-01 14:05:46 首次发布

本文链接：https://blog.csdn.net/qq_30332665/article/details/128129462

版权

【Smart-Doc】使用说明

前提

Version >= 2.6.2
基于注释生成代码，无需对项目本身做任何修改
注释不规范会导致生成后的文件注释缺失
项目地址：https://github.com/smart-doc-group/smart-doc
文档地址：smart-doc-group.github.io/#/

能做什么？

支持html静态页面，swagger2.0，openapi3.0，postman测试文件等自动生成。

基于注释生成相关文档，针对历史springboot Or springmvc项目，不需要对项目做任何修改，也能完整读取参数描述和接口url。

通过插件一键生成，不引入其他依赖，完全无入侵。（多module项目请先执行 mvn clean install）

生成html静态文件，方便本地查看。

生成postman文件，方便本地测试接口。

具体怎么用？

在pom中引入插件

<plugin>
    <groupId>com.github.shalousun</groupId>
    <artifactId>smart-doc-maven-plugin</artifactId>
    <version>2.6.2</version>
    <configuration>
    <!--配置文件位置-->
        <configFile>./src/main/resources/smart-doc.json</configFile>
        <projectName>test</projectName>
        <!--项目编译时执行生成html 不需要可以去掉executions 标签 -->
    <executions>
        <execution>
              <phase>compile</phase>
            <goals>
              <goal>html</goal>
            </goals>
        </execution>
    </executions>
</plugin>

配置文件 smart-doc.json

{
  "outPath": "D://md2", //存储位置
  "createDebugPage": true, //创建调试页 不推荐false
  "allInOne": true, //所有文档在一个html页面
}

多module项目怎么配置？

放在顶级pom文件中

├─parent 
├──common 
│ pom.xml
├──web1
  │ pom.xml
├──web2 
  │ pom.xml 
└─pom.xml

上面的maven结构假设是严格按照父子级来配置的，然后web1和web2都依赖于common，
这种情况下如果跑到web1下或者web2目录下直接执行mvn命令来编译都是无法完成的。需要在根目录上去执行命令编译命令才能通过，而smart-doc插件会通过类加载器去加载用户配置的一些类，因此是需要调用编译的和执行命令是一样的。这种情况下建议你建smart-doc-maven-plugin放到根pom.xml中，在web1和web2中放置各自的smart-doc.json配置。
然后通过-pl去指定让smart-doc生成指定模块的文档。

操作命令如下：

生成web1模块的api文档

mvn smart-doc:markdown -Dfile.encoding=UTF-8 -pl :web1 -am

生成web2模块的api文档

mvn smart-doc:markdown -Dfile.encoding=UTF-8 -pl :web2 -am

放在包含controller的子模块

通过插件调用，需要在顶级pom下执行 mvn clean install，不然直接执行插件可能会报错。（基于注释生成需要有源码（xxx-resource.jar）包）

在这里插入图片描述

提速和过滤

提速

速度太慢？插件里加个配置。

<plugin>
    <groupId>com.github.shalousun</groupId>
    <artifactId>smart-doc-maven-plugin</artifactId>
    <version>2.6.2</version>
    <configuration>
        <!--Specify the configuration file used to generate the document-->
        <configFile>./src/main/resources/smart-doc.json</configFile>
        <projectName>test</projectName>
        <includes>
        <!--公司或项目对应的包名 保证Request 和Response的实体能被加载到即可-->
            <include>com.test.example.*</include>
        </includes>
    </configuration>
</plugin>

过滤

只想生成部分contrloler包？配置文件里加配置
多个controller用 , 隔开，支持正则匹配

{
  "outPath": "D://md2",
  "createDebugPage": true,
  "allInOne": true,
  "packageFilters": "com.test.example.UserController"
}

原理说明

1. 基于QDox对Java源码解析，所以想要生成文档，必须保证能扫描到请求体和返回体的源码。这也是为什么在多module项目中，需要首先执行install的原因。
2. 为了更好的分析接口，插件会自动下载项目中所有的jar包源文件（对asm，spring系列等jar包有一定的过滤），所以不配置include标签会导致生成速度很慢。配置include标签建议只引入公司内的package。
3. 理论上，只需要保证接口层（controller）的请求体和返回体的类被扫描到即可。
4. 支持一些jackson，jsr303的使用，支持替换类，统一请求体，项目字典等配置，具体查看配置文档说明。

注释的使用说明

@param 特殊用法

smart-doc针对JAVA原生的@param添加一些特殊的用法。

对基本类型请求参数设置mock值

/**

Test @RequestParam
@param author 作者|村上春树
@param type type
*/ @GetMapping(“testRequestParam”) public void testRequestParam(@RequestParam String author, @RequestParam String
type){ }

上面通过|符号后面添加了作者的mock值为村上春树

参数对象替换

例如一些对象在框架底层做了特殊处理，smart-doc根据原始参数对象依赖过于强大的分析处理后的文档可能并不符合要求，这时你可以定义一个参数对象来
替换，然后smart-doc按照你指定的对象来输出文档。
例如：使用JPA的Pageable作为接口参数接收对象时Spring框架做了处理，实际上真正的属性是PageRequest,不过smart-doc如果采用PageRequest会推导出一些不必要的属性，
该功能从smart-doc 1.8.5开始提供。

/** 
* 参数对象替换测试 
* @param pageable com.power.doc.model.PageRequestDto 
* @return 
*/ 
@PostMapping(value = "/enum/resp") public SimpleEnum resp(@RequestBody Pageable pageable){ return null; }

上面的写法中smart-doc就会使用com.power.doc.model.PageRequestDto代替JPA的Pageable做文档渲染，注意类名必须是全类名。
下面来看smart-doc支持的书写方式 @param pageable
com.power.doc.model.PageRequestDto @param pageable
你的注释|com.power.doc.model.PageRequestDto

smart-doc本身基于泛型推导，如果需要泛型则需要写上具体的对象

@param pageable com.power.doc.model.PageRequestDto<com.power.doc.model.User>

尽量少采用这种参数替换的形式，代码书写很不方便，建议直接自己定义对象作为入参

@apiNote

@apiNote是JAVA新增的文档tag,smart-doc使用@apiNote的注释作为方法的详细描述，
因此可以使用@apiNote来写一段长注释。如果一个方法不写@apiNote注释说明，
smart-doc直接使用方法默认注释填充。@apiNote详细使用参考如下：

/** 
* 查询用户信息 
* @param name 用户名 
* @apiNote 通过用户的名称去查询到用户的详细信息 
* @return 
*/ 
@PostMapping(value = "/query") public String resp(@RequestBody String name){ return null; }

@deprecated

注意注解是@Deprecated，首字母是大写，这里说的是javadoc tag里面的。官方文档是这样描述的 Adds a comment
indicating that this API should no longer be used.

意思就是在注释里使用@deprecated标记该API已经弃用。

/** * 查询用户信息 
* @param name 用户名 
* @apiNote 通过用户的名称去查询到用户的详细信息 
* @deprecated
*  @return 
*/ 
@PostMapping(value = "/query") public String resp(@RequestBody String name){ return null; }

一些比较有意思的配置

smart-doc.json
更多配置参考：https://smart-doc-group.github.io/#/zh-cn/diy/config

{
    "isStrict": false,//严格的注释检查 当缺少注释或注释不规范时无法生成文档 默认false 
    "style":"xt256", //基于highlight.js的代码高设置
    "showAuthor":true,//是否显示接口作者名称，默认是true,不想显示可关闭
    "requestFieldToUnderline":true,//自动将驼峰入参字段在文档中转为下划线格式
    "responseFieldToUnderline":true,//自动将驼峰入参字段在文档中转为下划线格式
    "inlineEnum":true,//设置为true会将枚举详情展示到参数表中，默认false
    "ignoreRequestParams":[ //忽略请求参数对象，把不想生成文档的参数对象屏蔽掉
     "org.springframework.ui.ModelMap"
   ],
   "requestHeaders": [{ //设置请求头，没有需求可以不设置
      "name": "token",//请求头名称
      "type": "string",//请求头类型
      "desc": "desc",//请求头描述信息
      "value":"token请求头的值",//不设置默认null
      "required": false,//是否必须
      "since": "-",//什么版本添加的改请求头
      "pathPatterns": "/app/test/**",//请看https://smart-doc-group.github.io/#/zh-cn/diy/advancedFeatures?id=公共请求头
      "excludePathPatterns":"/app/page/**"//请看https://smart-doc-group.github.io/#/zh-cn/diy/advancedFeatures?id=公共请求头
  }]
}