【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=公共请求头}]
}

【Smart-Doc】使用说明相关推荐

Smart—doc配置
Smart-doc配置依赖 <dependency><groupId>com.github.shalousun</groupId><artifactId&g ...
电机的matlab仿真实例,电机控制Matlab仿真模型
[实例简介] 有5个电机仿真模型,包括开环V/F,永磁同步电机矢量控制.异步电动机的矢量控制.直接转矩控制等,欢迎下载.交流. [实例截图] [核心代码] 5种仿真模型 └── 5种电动机控制的MAT ...
我的软件推广成功之路 [转]
我的软件推广成功之路本人与大家一样,原来只是一个普通的程序员,靠给软件公司打工谋生.后来感觉这样长期干下去没有什么前途,虽然现在年轻还可以加班加点靠拼身体吃饭,以后年纪大了怎么办?听说很多人自己单干 ...
html5游戏偷菜源码,偷菜游戏原码
[实例简介] 偷菜游戏,功能说明: 一.PP农场 1.1.果币支持兑入兑出 1.2.种植.收取.铲除.偷菜等基本功能 1.3.支持签到功能 1.4.常规任务系统 1.5.道具功能(化肥.增加植物生长速 ...
smart-doc初体验-springboot生成自动文档
smart-doc初体验一.为什么要引入smart-doc? 二.对比swagger 三.使用四.讨论 1.设计先行模式 2.代码先行五.体验六.附录 1.完整的配置项: 2.官方地址: 一. ...
ubuntu常用命令，tar的基本用法
ubuntu常用命令 tar 常用 # 将 file.tar.gz 解压 tar -zxvf file.tar.gz # 将压缩目标压缩为 file.tar.gz tar -zcvf file.t ...
猿创征文｜小而巧的API文档生成工具之smart-doc
文章目录 smart-doc介绍 smart-doc特性 smart-doc的最佳搭档谁在使用smart-doc smart-doc的优缺点 smart-doc和swagger区别比较 smart- ...
我的软件推广成功之路
本人与大家一样,原来只是一个普通的程序员,靠给软件公司打工谋生.后来感觉这样长期干下去没有什么前途,虽然现在年轻还可以加班加点靠拼身体吃饭,以后年纪大了怎么办?听说很多人自己单干每年靠共享软件都可以赚 ...
计算机基础考试系统怎么使用,计算机基础课程考试系统使用说明.doc
计算机基础课程考试系统使用说明.doc 考试系统使用说明学生使用方法 IE浏览器地址栏中输入13中,用户名为学生的学号,默认密码也为学生的学号.登录后如下图所示: 单击"在线考试" ...
das服务器未响应,DAS软件使用说明-link.doc
DAS软件使用说明-link.doc IP广播软件使用说明目录一.前言3 1.1.系统简介3 1.2.硬件软件要求3 2.3.安装方法及过程3 二.服务管理软件4 2.1.服务器4 2.1.1.基 ...

【Smart-Doc】使用说明

【Smart-Doc】使用说明

前提

能做什么？

具体怎么用？

在pom中引入插件

配置文件 smart-doc.json

多module项目怎么配置？

放在顶级pom文件中

生成web1模块的api文档

生成web2模块的api文档

放在包含controller的子模块

提速和过滤

提速

过滤

原理说明

注释的使用说明

@param 特殊用法

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

参数对象替换

@apiNote

@deprecated

一些比较有意思的配置

【Smart-Doc】使用说明相关推荐

最新文章

热门文章

【Smart-Doc】 使用说明

【Smart-Doc】 使用说明

前提

能做什么？

具体怎么用？

在pom中引入插件

配置文件 smart-doc.json

多module项目怎么配置？

放在顶级pom文件中

生成web1模块的api文档

生成web2模块的api文档

放在包含controller的子模块

提速和过滤

提速

过滤

原理说明

注释的使用说明

@param 特殊用法

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

参数对象替换

@apiNote

@deprecated

一些比较有意思的配置

【Smart-Doc】 使用说明相关推荐

最新文章

热门文章

【Smart-Doc】使用说明

【Smart-Doc】使用说明

【Smart-Doc】使用说明相关推荐