api-doc致力于减轻开发人员写接口文档的负担,希望可以以最小的代价,快速生成接口文档。

我们尽量规避复杂注解,以极简的方式,生成丰富的文档内容,即所谓代码即文档

它有如下几个优点:

  1. 配置足够少,上手简单,默认配置能满足大部分场景
  2. 非侵入式,极少的额外注解(非必须的),使用常规功能时不用修改现有代码
  3. 多层次的字段翻译功能,减少不必要的重复劳动
  4. 除@Controller外,也支持@RpcService,以及以FunctionCode路由功能的web接口

注意

对于请求参数、响应参数的解析,是依赖Javadoc的API进行的,它要求参数必须有明确的结构,因此api-doc不支持以Map作为参数的方法解析。

api-doc-process

一、三步完成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中的插件

api-doc-rn

控制台中打印出类似内容,代表执行成功。默认情况下,插件不绑定maven的生命周期。

succ-result

step 3. 查看Yapi平台成果

注意

接口方法注释将成为Yapi菜单的名称,注意为接口方法添加注释。
接口排列顺序,是按照首字母升序排列的,建议同一功能模块具有相同的前缀名称。

ypai-result

二、关于请求、响应参数字段的翻译

为了避免翻译字段时的重复劳动,不停添加相同的注释,api-doc提供了多种获得注释的方式。

translate

当前一种方式无法获得中文注释时,会自动尝试下一种获取方式。点击链接查看远程字典的示例。

同一个项目中的命名习惯,通常是有迹可循的,理想状况下,将远程字典调教好,代码中仅需个别的字段需要手动添加注释。

三、更多配置说明

除了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>

附:已知缺陷说明:

  1. 对泛型支持有限,仅支持集合类(Collection、List、Set)中使用泛型; 不支持集合中嵌套集合,如List<List>
  2. 对数组支持有限,推荐使用集合类(Collection、List、Set)
  3. 不支持单个文件的文档更新,每次都是全量更新,所以更新文档前需要保持本地代码是最新的

附:2.0版本展望:

  1. maven插件只能批量操作,计划增加IDEA插件,以支持单文件操作
  2. 导入Yapi时,支持为接口分类、排序

文章作者: 沉迷思考的鱼
版权声明: 本博客所有文章除特別声明外,均采用 CC BY 4.0 许可协议。转载请注明来源 沉迷思考的鱼 !
 本篇
api-doc 使用说明 api-doc 使用说明
api-doc致力于减轻开发人员写接口文档的负担,希望可以以最小的代价,快速生成接口文档。 我们尽量规避复杂注解,以极简的方式,生成丰富的文档内容,即所谓代码即文档。 它有如下几个优点: 配置足够少,上手简单,默认配置能满足大部分场景 非
2020-07-18 沉迷思考的鱼
下一篇 
文档自动化生成设计 文档自动化生成设计
文档自动化生成组件,有如下几个设计目标: 配置足够少,上手简单,默认配置能满足大部分场景 非侵入式,不用修改现有代码 方式灵活,支持批量操作和单个操作 代码即文档,将代码里所有的注释转化到文档里(即使是非文档注释) 1. 支持的检测范围
2020-06-18 沉迷思考的鱼
  目录