下面是关于接口文档生成-一键生成文档

一键生成文档

打开apipost点击分享文档

复制并打开文档地址就可以看到了完整的接口文档。

本节课主要是讲解一些需要注意的事项。

请求参数的描述填写

对于header、query以及form-data和urlencode的body参数，我们在如下地方填写参数描述：

如图中所示，对于一个填写过的参数，我们可以在新建接口可以通过点击参数描述后面的♦️方块标志快速导入描述，不用重复打字。

对于raw类型的body参数，我们可以通过点击“提取字段和描述”来针对参数进行描述的填写：

对于已经填写过的参数，APIPOST会自动匹配描述，不用重复填写。

响应参数的描述填写

很多新手困惑为什么APIPOST分享的文档没有成功响应示例和错误响应示例，那是因为APIPOST不会把发送后的实时响应的数据作为响应示例。

您需要手动的将实时响应结果导入或者复制到对应的成功响应示例和错误响应示例。

字段描述的填写跟raw类型的body参数，我们可以通过点击“提取字段和描述”来针对参数进行描述的填写。

同样，对于已经填写过的参数，APIPOST会自动匹配描述，不用重复填写。

本文主要分享一个基于个人兴趣，旨在提高工作效率，开发了一个基于文档注释，接口文档生成工具，欢迎大佬指点。

1.前置介绍

1.1前世

现在大多数项目都走向了前后端分离，前后端并行开发，这就需要后端同学在开发前先写好接口文档。很多时候开发人员一般都会选择，自己手写文档，或者使用目前开源的API工具，包括现在比较火的swagger但劣势也不少

Swagger分析：
1).为生成规范的接口文档，需要添加各种各样的注解，代码侵入性太强；
2).增加了人工成本，做了多余的事;
3).增加复杂度，代码越多复杂性越差；
4).需要遵守其特殊的规范；

图示示例：

1.2深思

问题：能不能根据参数类中的文档注释生成接口文档呢 ？作为程序员，代码不应该即是文档吗？
那我们现在的需求是什么呢 ？
1).代码侵入性小，配置简单 、层级结构清晰、可输出参数示例demo；
2).无需太复杂的功能，只要可以生成文档即可 ；
3).最好是支持转换成语雀，方便存档；

带着好奇心与兴趣开始考虑？如何获取文档注释？
遇到的最大难点就是：代码编译后会自动去除注释；
从编译后的代码里获取肯定是行不通的。思维转变，编译后取不到，那就从未编译的文件里获取。

1.3今生

根据文档注释生成接口文档工具，在空余时间研究并开发，已经基本完成分享使用。
主要用到的技术点
IO、反射、Freemarker模板引擎、Markdown语法

2.功能介绍

2.1主要功能

(1).读取文档注释

• 读取参数类中属性文档注释；

• 读取controller方法文档注释；

• 读取接口类文档注释；

(2).支持复杂参数

• 参数层级嵌套，继承父类；

• 支持返回值，泛型格式输出（根据一些关键词 T、Object、、等判断的）；

(3).统一网关类接口文档生成

• 支持生成统一网关接口的文档，自定义@OpenApi注解的读取；

(4).根据注解获取请求类型

• 支持根据接口注解获取请求类型，示例：@PostMapping；

(5).根据注解判断参数是否非空

• 支持根据注解**[@NotBlank,@NotNull,@NotEmpty]**判断入参是否必填，返回参数默认非空；

(6).根据注解判断参数长度

• 支持根据注解**[@Max,@Min,@Size,@Length,@DecimalMax,@Range,@DecimalMin] **输出入参长度；

(7).生成JSON示例

• 支持输出json格式参数Demo示例；

• 支持根据类型以及名称模拟值；

(8).生成统一结构MD接口文档

• 生成MD接口文档；

• 支持拷贝到语雀平台，文档格式依然存在；

(9).文档参数类型转换

• 支持参数驼峰转下划线转换 ;

(10).排序规则

• 参数属性排序 > 以类中属性从上往下顺序排序；

• 接口方法排序 > 以类中方法从上往下顺序排序；

2.2.优缺点

优点:
(1).代码非侵入性，无需添加一些无用的注解；
(2).无需引入依赖生成，减少与业务项目耦合度；
(3).可以自定义一些功能；
(4).早日实现代码即文档的期盼，减少人工编写接口文档的时间；

缺点：
(1).返回参数多级需要使用泛型；
(2).拷贝到语雀后样式兼容差强人意；

2.3.示例图

3.特殊规则

** 注：未按照如下规则，可能会导致无法生成完整文档或失败。**

3.1参数类文档注释匹配-特殊规则
(1).内部类支持不太完善；

3.2Controller接口方法类规则
(1).返回值支持自定义类，统一返回Response,需要加泛型，否则获取不到嵌套的返回值，示例：Response ;
(2).同一个controller类方法名称建议不相同，重名情况下可能会导致方法注释匹配错误问题 ;
(3).java.包下的返回值暂不支持 ;
(4).private方法会自动过滤 ;
(5).相同方法名，重载的方法，可能会出现注释匹配错误 ;

4.使用方式

• 文档生成的是md文件支持Markdown语法

• 目前支持两种使用方式， 方式一：外置工具方式 方式二：依赖jar包+启动类方式 两种方式功能一致，可选择性使用。推荐使用侵入性较小的外置工具方式。

4.1外置工具生成

注：外置工具生成，指的是无需引入工具jar包方式生成

4.1.1精简版使用示例

1).下载工具包

源码地址

注意：下载后解压路径，最好不要有中文路径

可执行jar解压后文件示例

文件介绍

• ApiGeneratorConfig.xml > 当前配置文件

• ApiGeneratorConfig_orgin.xml > 全配置文件

• api-document-generate.jar > 生成工具Jar

• start.bat > Win 系统下启动

• start.command > ios 系统下启动

下载完工具后，可打开源码可执行jar目录下ApiGeneratorConfig.xml配置成相应的自己电脑的示例工程目录即可开始生成

2).配置ApiGeneratorConfig.XML

<?xml version="1.0" encoding="UTF-8" ?>
<config>    <!-- 生成类型 1-根据包地址生成，包下所有类的接口 2-自定义类生成 -->
    <generateType value="1"/>    <!-- 项目下类扫描路径（绝对路径）, 支持多个 , 一般是项目根路径 -->
    <projectScanPaths>
        <path value="/Users/xx/project/api-generate-demo"/>
    </projectScanPaths>    <!-- 包文件夹地址（绝对路径,生成类型为1时必填） -->
    <apiPackagePath
            value="/Users/xx/project/api-generate-demo/api-generate-web02/src/main/java/com/example/controller"/>    <!-- 类文件地址（绝对路径,生成类型为2时必填）-->
    <apiClassPaths>
        <path value=""/>
    </apiClassPaths>

</config>

启动注意事项

• 启动前需要配置好XML文件中的内容；

• 配置文件获取路径默认是当前运行路径下名称为 ApiGeneratorConfig.xml；

• 生成文件默认地址 ：当前运行路径下 generate 文件夹下；

Win 系统下启动 双击 start.bat
ios 系统下启动 双击 start.command

4.1.2全功能配置指南

1).根据包地址生成

<?xml version="1.0" encoding="UTF-8" ?>
<config>    <!-- 生成类型 1-根据包地址生成，包下所有类的接口 2-自定义类生成 -->
    <generateType value="1"/>    <!-- 项目下类扫描路径（绝对路径）, 支持多个 -->
    <projectScanPaths>
        <path value="/Users/xx/project/api-generate-demo"/>
    </projectScanPaths>    <!-- 包文件夹地址（绝对路径,生成类型为1时必填） -->
    <apiPackagePath
            value="/Users/xx/project/api-generate-demo/api-generate-web02/src/main/java/com/example/controller"/>

</config>

2).根据类地址生成

<?xml version="1.0" encoding="UTF-8" ?>
<config>    <!-- 生成类型 1-根据包地址生成，包下所有类的接口 2-自定义类生成 -->
    <generateType value="2"/>    <!-- 项目下类扫描路径（绝对路径）, 支持多个 -->
    <projectScanPaths>
        <path value="/Users/xx/project/workproject/fshows-finance"/>
    </projectScanPaths>    <!-- 类文件地址（绝对路径,生成类型为2时必填）-->
    <apiClassPaths>
        <path value="/Users/xx/project/workproject/fshows-finance/fshows-finance-openapi/src/main/java/com/fshows/finance/service/FeeCodeApiService.java"/>
        <path value="/Users/xx/project/workproject/fshows-finance/fshows-finance-openapi/src/main/java/com/fshows/finance/service/PayableApiService.java"/>
    </apiClassPaths>
</config>

3).统一网关类型接口配置

<!-- 开放接口注解类配置, annotationFieldName 默认 "method" --><gateWayField annotationName="com.fshows.finance.common.annotation.OpenApi" annotationFieldName="method"/>

4).根据参数名排除

<!-- 排除参数名配置（支持多个） --><apiExcludeParamNames>
  <paramName value="nonce"/>
  <paramName value="sourceType"/>
</apiExcludeParamNames>

5).根据参数全路径排除

  <!-- 排除参数全类名配置（支持多个） -->
    <apiExcludeParamClassNames>
        <paramClassName value="com.demo.param.UserLoginResult"/>
    </apiExcludeParamClassNames>

6).Json示例生成开关

<!-- 是否生成 1-是,2-否 默认1 --><generateJsonFlag value="2"/>

7).参数类型转换

<!-- 参数类型 1-默认,2-驼峰转下划线 --><apiParamType value="2"/>

8).生成文件路径配置

注：生成文件默认名称，Api-generate-MMddHHmmss.md
默认路径是当前项目路径,路径可自定义

<!-- 生成文件地址(默认：当前目录) --><generateFilePath value="/Users/mengqiang/Desktop/api-generate-tool/finance/openapi"/>

9).项目请求地址根路径

<!-- 项目接口访问根路径 默认无 --><projectRootUrl value=""/>

10).自定义统一返回对象

注：一些接口中未包含统一返回对象，但是希望生成的文档包含此结构
参数含义依次为： 参数名, 参数类型, 参数描述, 是否作为父级
是否作为父级标识为是情况下将会，把原先的返回参数添加到该父级下

<!-- 自定义顶级返回对象属性 --><apiRootResField>
  <field name="success" typeClassName="java.lang.Boolean" desc="请求是否成功" isParent="0"/>
  <field name="data" typeClassName="java.lang.Object" desc="" isParent="1"/>
  <field name="errorCode" typeClassName="java.lang.String" desc="错误码" isParent="0"/>
  <field name="errorMsg" typeClassName="java.lang.String" desc="错误信息" isParent="0"/>
</apiRootResField>

11).接口头信息输出

针对接口文档存在统一头信息情况下使用，可以在每一个接口中添加头信息参数

<!-- 请求 contentType --><contentType value="application/x-www-form-urlencoded"/><!-- 头信息 --><apiHeaderField>
  <field name="token" type="String" desc="当前登录用户token" isRequired="1"/>
</apiHeaderField>

5.文件查看

5.1.[推荐]打开工具

Demo示例图：

4.2.2.文本形式查看

支持以文本形式打开文件，直接拷贝内容粘贴到语雀文档中


注：输出使用的是Markdown 语法，若拷贝到语雀粘贴时请点击进行转换，
建议采用工具打开后，再拷贝到羽雀，
使用文本格式拷贝到语雀后会被重新编译，内容会存在多余的空行。**

转换后示例：

6.附言

万物有痕，可能会有一些未考虑到场景或问题，欢迎大佬指点。

以上就是小编为大家整理的接口文档生成-一键生成文档

版权声明：本文内容由网络用户投稿，版权归原作者所有，本站不拥有其著作权，亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容，请联系我们jiasou666@gmail.com 处理，核实后本网站将在24小时内删除侵权内容。