api-doc致力于减轻开发人员写接口文档的负担,希望可以以最小的代价,快速生成接口文档。
我们尽量规避复杂注解,以极简的方式,生成丰富的文档内容,即所谓代码即文档
。
它有如下几个优点:
- 配置足够少,上手简单,默认配置能满足大部分场景
- 非侵入式,极少的额外注解(非必须的),使用常规功能时不用修改现有代码
- 多层次的字段翻译功能,减少不必要的重复劳动
- 除@Controller外,也支持@RpcService,以及以FunctionCode路由功能的web接口
注意
对于请求参数、响应参数的解析,是依赖Javadoc的API进行的,它要求参数必须有明确的结构,因此api-doc不支持以Map作为参数的方法解析。
一、三步完成api-doc的引入和使用
step 1. 添加插件
<plugin>
<groupId>com.ly.fn.biz.api-doc-maven</groupId>
<artifactId>api-doc-maven-plugin</artifactId>
<version>1.0.0-SNAPSHOT</version>
<configuration>
<yapiToken>a7106c02912fff91858cf721175ea16b99bff8141c29aaa1da1d4020c5d7053f</yapiToken>
</configuration>
</plugin>
其中yapiToken
是从Yapi平台的项目设置中得到的,插件通过它定位具体的Yapi项目。
step 2. 运行插件
进入项目根目录,运行如下命令
mvn api-doc:api-doc
或者双击IDEA中的插件
控制台中打印出类似内容,代表执行成功。默认情况下,插件不绑定maven的生命周期。
step 3. 查看Yapi平台成果
注意
接口方法注释将成为Yapi菜单的名称,注意为接口方法添加注释。
接口排列顺序,是按照首字母升序排列的,建议同一功能模块具有相同的前缀名称。
二、关于请求、响应参数字段的翻译
为了避免翻译字段时的重复劳动,不停添加相同的注释,api-doc提供了多种获得注释的方式。
当前一种方式无法获得中文注释时,会自动尝试下一种获取方式。点击链接查看远程字典的示例。
同一个项目中的命名习惯,通常是有迹可循的,理想状况下,将远程字典调教好,代码中仅需个别的字段需要手动添加注释。
三、更多配置说明
除了yapiToken
,插件还支持一些其它配置,完整版的配置示例如下:
<configuration>
<yapiUrl>http://yapi.itcjf.com</yapiUrl><!-- yapi 平台地址,可以不填写,默认是公司的平台地址 -->
<yapiToken>a7106c02912fff91858cf721175ea16b99bff8141c29aaa1da1d4020c5d7053f</yapiToken> <!-- 所属项目,必录 -->
<!-- 可选的,远程的字典目录,可以用它翻译公共的字段,避免重复写注释 -->
<dictionaryUrl>
http://gitserver/ypk15904/biz-lw-factory-web-api-doc/raw/master/biz-lw-factory-web.properties
</dictionaryUrl>
<!-- 可选的,免费的百度翻译API参数,需要自行注册使用,当代码注释、远程字典都翻译失败时,将使用它 -->
<baiduTransAppId>20200712000517786</baiduTransAppId>
<baiduTransKey>6RoUOwrR86lK8X_kWYC3</baiduTransKey>
<!-- 可选的,默认开启三种类型的扫描 -->
<scanScope>spring-mvc,xpro-rpc,abstract-class</scanScope>
<!-- 可选的,指定拥有共同父类的API接口 -->
<abstractMethod>com.ly.api.doc.maven.handler.AbstractHandler#handle</abstractMethod>
<!-- 可选的,指定想要排除的包,被排除后将不再生成该包下的API接口 -->
<excludePackages>
<param>com.ly.api.doc.maven.excludepackage2</param>
<param>com.ly.api.doc.maven.excludepackage3</param>
</excludePackages>
<!-- 可选的,指定想要排除的类,被排除后将不再生成该类下的API接口 -->
<excludeClassNames>
<param>com.ly.api.doc.maven.handler.Sample2Handler</param>
</excludeClassNames>
<!-- 可选的,默认情况下插件仅解析当前项目中的源文件,通过该配置可以扩大参数的解析范围 -->
<extraParamsPackages>
<param>com.ly.fn.biz.lw.linen.api</param>
</extraParamsPackages>
</configuration>
附:已知缺陷说明:
- 对泛型支持有限,仅支持集合类(Collection、List、Set)中使用泛型; 不支持集合中嵌套集合,如List<List
> - 对数组支持有限,推荐使用集合类(Collection、List、Set)
- 不支持单个文件的文档更新,每次都是全量更新,所以更新文档前需要保持本地代码是最新的
附:2.0版本展望:
- maven插件只能批量操作,计划增加IDEA插件,以支持单文件操作
- 导入Yapi时,支持为接口分类、排序