SpringBoot-YApi文档生成器

SpringBoot-YApi文档生成器

充分利用springboot自有注解来对文档进行描述的一款文档生成器。

YDoc源码Github仓库地址

引言

每当工程需要接口文档时，总会使用Swagger一类的restfulApi文档生成工具，相信很多人在使用时都会被它的一些注解和配置恶心到，如果工程对代码规范无要求还能作为注释来看，如果需要再写Javadoc注释就无形中增加了工作量，为了更加简单的使用我写了一款基于spring-boot-starter的依赖库，它基于YApi平台可以统一管理api文档和权限控制，mock数据等

1. 对比其他文档生成器

这里举两种java平台常用的api文档生成器。

1.JDoc

JDoc是根据文档注释去生成api文档的工具，需要遵循JDoc定义的文档规范进行书写才能生成对应的接口文档，不支持mock数据,权限管理等，不能集中管理Api，强制依赖于Javadoc规范实现，静态页面部署不方便，对离线支持好。

• 优点是只需要写Javadoc即可无需引入额外配置。
• 缺点是强制依赖于Javadoc规范,对api测试不友好，生成需额外操作。

2.Swagger

Swagger是基于注解形式生成api文档的工具，对接口的参数，返回值等都需要加对应的注释才能生成对应的api文档，支持api测试，不支持mock数据,权限管理等，不能集中管理Api，不方便离线，随程序部署而部署。

• 优点是操作简单，接口生成的比较好，随程序部署而部署使用方便。

• 缺点是集成麻烦，依赖大量注解，增加开发成本。

  3.YDoc

  Ydoc是一款基于spring-boot-starter的依赖库，轻量级，无Ui界面，不依赖注释，少量依赖注解和使用规范，整体依赖于YApi接口可视化平台，可使用YApi的所有特征，与程序部署分离可集中化管理，支持权限控制等，集成快速高效，配置依赖，加上两行配置程序启动时即可自动生成。

• 优点是可使用YApi平台的特性，侵入性更低，0配置，引入依赖添加配置文件即可。

• 缺点是少量依赖注解和使用规范，仅支持spring-boot工程

2. YDoc的使用方法（基于YApi版本1.9.2）

1. 需搭建YApi文档平台（YApi官方文档）
2. 引用ydoc-spring-boot-starter依赖
3. 在配置文件中配置YApi的url，以及项目的token

如果不能直接依赖说明还没有同步到中央maven仓库过几天应该就可以了

com.github.nobugboy
ydoc-spring-boot-starter
1.0.1

配置名	值	是否必须
ydoc.token	YApi项目中生成的token	是
ydoc.host	YApi的url,例http://localhost:3000	是
ydoc.enable	程序启动时是否同步到YApi平台	是
ydoc.print	程序启动时是否打印离线JSON（可手动导入到YApi）	否

3. YDoc的使用步骤

1. 在搭建好的YApi平台上创建好对应工程的项目
2. 点开项目，设置-token配置，复制好token粘贴到Java工程的对应配置上
3. 启动应用即可

4. 参数描述

注解	值
@RestController	注解中value描述controller的作用，默认为controller名
@RequestMapping	注解中name描述该api的作用，在类上加跟路径时不需要name
@RequestParam	注解中name描述该参数的作用
@PathVariable	注解中name描述该参数的作用
@GetMapping	注解中name描述该api的作用
@PostMapping	注解中name描述该api的作用
@DeleteMapping	注解中name描述该api的作用
@PutMapping	注解中name描述该api的作用
@ParamDesc	注解中value描述该参数的描述，required是否必须
@ParamIgnore	忽略参数

其中@ParamDesc与@ParamIgnore为额外的注解，其余为SpringBoot的注解，@ParamDesc用来标识实体中参数的描述，@ParamIgnore用来忽略参数不参与生成文档，如不加参数描述则默认为参数的名称。 针对enum类型，需要重新toString方法,返回一个json字符串作为描述参数。

5.使用YDoc规范建议

1. 无论是什么请求，如果使用对象接收对象内的基本类型建议使用包装类
2. 建议在参数上加@ParamDesc用来描述作用
3. spring提供的注解再原有开发习惯上加name，用来描述RestController或Api的作用
4. 如有特殊参数例如Bindingresult，登录的用户实体等使用@ParamIgnore进行忽略

6.话外音

参数描述的注解是逼不得已。后续会考虑加入@valid相关的处理，从中考虑是否可以"见缝插针"