api-doc 使用说明 | 沉迷思考

无标签

api-doc 使用说明

发布日期: 2020-07-18

文章字数: 1.1k

阅读时长: 4 分

阅读次数:

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

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

它有如下几个优点：

配置足够少，上手简单，默认配置能满足大部分场景
非侵入式，极少的额外注解(非必须的)，使用常规功能时不用修改现有代码
多层次的字段翻译功能，减少不必要的重复劳动
除@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>