API文档管理工具

johnny233

已于 2023-02-07 16:23:36 修改

阅读量1.4w

点赞数 1

分类专栏： Tool 文章标签：文档管理

于 2018-10-20 21:44:05 首次发布

本文链接：https://blog.csdn.net/lonelymanontheway/article/details/83177403

版权

Tool 专栏收录该内容

51 篇文章 8 订阅

订阅专栏

系统庞大之后，前后端分离开发，前端调用后端提供的接口，请求协议一般是 HTTP，数据格式一般是 JSON。后台只负责数据的提供和计算，而完全不处理展现逻辑和样式；前端则负责拿到数据，组织数据并展现的工作。这样结构清晰，关注点分离，前后端会变得相对独立并松耦合。好处多多。

但是这样带来很多问题，前端可能需要拿到后端的数据之后，才能开始开发工作，等前端开发完成之后，然后再与后端一起联调。耗时不说，如果业务的需求更改，后端接口变更，怎么快速便捷告知前端的开发人员？还有其他如文档维护和及时更新的问题。这样一来，编写文档也是个不小的负担。

此时就需要一个在线接口文档平台/工具，提供接口的请求参数 requestBody 和响应参数 responseBody 的数据结构定义。但是仅仅有 requestBody 和 responseBody 的数据结构还是不行的，前端调用后端的接口时没有响应数据（接口还没有开发好），前端并不能开始干活。故而我们进一步要求这些工具具备模拟出真实数据的能力，即所谓的 mock server功能，暂时替代后台服务，这样方便前端联调。

考虑到文档及时更新的负担，将文档写在代码里，开发人员编写代码时同时修改文档。然后通过工具从代码中抽出文档，并生成方便用户阅读的格式。此类工具早已存在，比如Java中的 javadoc，其他诸如：swagger、apiDoc。

这类工具真的不要太多，到底哪个好用上手方便安装简单还真是众口难调的问题，而且需要试用一段时间才有感觉和感受，有时间成本在里面。不过，一般看团队看架构师的选择。

swagger

官网：https://swagger.io/
Swagger 是一款RESTful 接口的文档在线自动生成+功能测试功能软件，一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务，让部署管理和使用功能强大的API 变得简单。swagger，提供一种从项目代码中自动生成接口文档的功能，可以保持和代码的同步变化。通过 Swagger 你可以获得项目的一种交互式文档，客户端SDK的自动生成等功能。

Swagger提供的工具：

Swagger Core：Swagger-core 是 Swagger的Java 实现，核心实现；
Swagger Codegen：提供根据swagger的接口定义文件(yaml形式)，以一种命令行工具的形式，直接生产相应的代码；
Swagger Editor：使用 yaml 语言先定义简单的接口，然后通过 Swagger-codergen 就可以自动生成相应的服务端和客户端的调用代码；

springboot 集成 swagger

添加@Configuration & @EnableSwagger2 注解的配置类

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("fm.web"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("freemarker project RESTful APIs")
                .description("this is freemarker app swagger-ui page")
                .version("1.1")
                .build();
    }
}

pom.xml 添加：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

参考GitHub

常用注解
TODO: 待整理。
使用ApiImplicit
Params描述多个参数
(2) 使用ApiImplicitParam时，需要指定paramType,这样也便于swagger ui 生成参数的输入格式。
paramType 有五个可选值： path, query, body, header, form

ApiImplicitParam 与 ApiParam 的区别
ApiImplicitParam: This is the only way to define parameters when using Servlets or other non-JAX-RS environments。
对Servlets或者非 JAX-RS的环境，只能使用 ApiImplicitParam。
在使用上，ApiImplicitParam比ApiParam具有更少的代码侵入性，只要写在方法上就可以了，但是需要提供具体的属性才能配合swagger ui解析使用。
ApiParam只需要较少的属性，与swagger ui配合更好。
ModelAttribute 是Spring mvc的注解，这里Swagger可以解析这个注解，获得User的属性描述。

Swagger2Markup

主要用来将Swagger自动生成的文档转换成几种流行的格式以便于静态部署和使用，比如：AsciiDoc、Markdown、Confluence。基于Swagger，生成静态API文档，以便于构建更轻量部署和使用的API文档。
开源主页：https://github.com/Swagger2Markup/swagger2markup

Swagger Editor

有在线版 https://editor.swagger.io/
也可以本地安装：

git clone git@github.com:swagger-api/swagger-editor.git
cd swagger-editor
npm install
npm start
npm install -g http-server #安装服务器
unzip swagger-editor.zip #解压
http-server swagger-editor #启动swagger-editor
# 访问http://localhost:8080 即可看到。

契约测试

所以，在一开始就定一个契约就成迫在眉睫的事情，双方就API相关的内容，包括路径、参数、类型等达成一致，当然，这份契约并不是一旦创建就不能修改的，而且，如果一开始没有设计好，很有可能会频繁的修改。这个时候，要让双方都能够实时的跟踪最新的API就成了一个难题。还好，在总结前人的经验和教训之后，早已有应对之策，那就是契约测试。
首先，我们先假设我们已经有了一份契约；然后，前端会根据这份契约建立一个Mock server，所有的测试都发往这个Mock server。有两方面的原因：一是这个时候可能后台的API还没有开发完成；二是有可能因为网络等其他方面的原因导致直接调用真实的后台API会很不稳定或者很耗时。如果后台的API实现和之前约定的并不一样，怎么能保证到集成的时候双方还能很顺利的集成呢？只需要让前端的测试定期连接真实的API执行一遍就能尽早的发现差异性。相应的测试和契约定义就需要更新以满足最新的业务需求。
总之，进行契约测试的目的就是尽早的发现差异性，并作出调整，将最后集成的风险降到最低。

对 swagger 的吐槽：
耦合性太强，重复的注解信息？

YApi

简介

官网
 Github
YApi 由 YMFE（去哪儿大前端团队 & 移动架构组，由FE，iOS和Android工程师共同组成）开源，旨在为开发、产品、测试人员提供更优雅的接口管理服务，可以帮助开发者轻松创建、发布、维护 API。
特性

基于 Json5 和 Mockjs 定义接口返回数据的结构和文档，效率提升多倍；
免费开源，内网部署，信息不会泄露；
权限管理，扁平化权限设计，即保证大型企业级项目的管理和易用性，满足各类企业的需求；
可视化接口管理基于 websocket 的多人协作接口编辑功能和类 postman 测试工具，让多人协作成倍提升开发效率；
Mock Server 易用的 Mock Server，除支持普通的随机 mock 外，还增加 Mock 期望功能，根据设置的请求过滤规则，返回期望数据；
自动化测试完善的接口自动化测试，支持对 Response 断言，保证数据的正确性；
数据导入支持导入 swagger, postman, har 数据格式，方便迁移旧项目；
插件机制强大的插件机制，满足各类业务需求；

安装

使用 Docker 安装 YApi

1、创建 MongoDB 数据卷
docker volume create mongo_data_yapi
2、启动 MongoDB
docker run -d --name mongo-yapi -v mongo_data_yapi:/data/db mongo
3、获取 YApi 镜像，并打 tag

docker pull registry.cn-hangzhou.aliyuncs.com/anoy/yapi
docker tag registry.cn-hangzhou.aliyuncs.com/anoy/yapi yapi

4、初始化 YApi 数据库索引及管理员账号

docker run -it --rm \
  --link mongo-yapi:mongo \
  --entrypoint npm \
  --workdir /api/vendors \
  yapi \
  run install-server

5、启动 YApi 服务：

docker run -d \
  --name yapi \
  --link mongo-yapi:mongo \
  --workdir /api/vendors \
  -p 3000:3000 \
  yapi \
  server/app.js

安装成功，访问地址 http://localhost:3000

CentOS 系统安装

# 安装 Node.js
curl --silent --location https://rpm.nodesource.com/setup_8.x | sudo bash -
yum -y install nodejs
# 安装编译工具包
yum install gcc-c++ make -y
# 安装配置MogoDB数据库
cd /etc/yum.repos.d/
vim mongodb.repo

[mongodb]
name=MongoDB Repository
baseurl=http://downloads-distro.mongodb.org/repo/redhat/os/x86_64/
gpgcheck=0
enabled=1

yum install mongodb-org -y
# 启动服务
service mongod start
ps -ef|grep mongod
lsof -i :27017
# 创建数据库
mongo

命令：

use yapi
db.wong.insert({“name”:“kenny wong”})
show dbs
db.createUser(‘yapi’,‘yapi321’)

# 安装YApi 软件
mkdir yapi
cd yapi/
git clone https://github.com/YMFE/yapi.git vendors
cp config_example.json ../config.json
vim config.json

{
  "port": "3000",
  "adminAccount": "admin@admin.com",
  "db": {
    "servername": "127.0.0.1",
    "DATABASE":  "yapi",
    "port": 27017,
    "user": "yapi",
    "pass": "yapi321"
  },
  "mail": {
    "enable": true,
    "host": "smtp.163.com",
    "port": 465,
    "from": "***@163.com",
    "auth": {
        "user": "***@163.com",
        "pass": "*****"
    }
  }
}

npm install --production --registry https://registry.npm.taobao.org
# 启动服务
npm run install-server
node server/app/js
# 或者以后台服务形式运行
node server/app/js &

apiDoc

官网：http://apidocjs.com/
GitHub：https://github.com/apidoc/apidoc
apiDoc，基于NodeJS实现，不基于任何框架，非常轻量级，适用于几乎所有流行语言，针对Restful API的文档自动生成工具。文档写在注释里面，提供历史版本比较功能。
安装：npm install apidoc -g
文档生成：apidoc -i src -o dest，该命令从当前工作目录的src子目录下读取所有代码文件，并从中抽取apiDoc的文档注释，然后生成HTML格式的文档，并保存在dest子目录下。

入门

在项目的主目录新建一个apidoc.json文件

{
  "name": "example",
  "version": "0.1.0",
  "description": "A basic apiDoc example"
}

接口添加注释：

/**
* @api {POST} /register 注册用户
* @apiGroup Users
* @apiVersion 0.0.1
* @apiDescription 用于注册用户
* @apiParam {String} account 用户账户名
* @apiParamExample {json} 请求样例：
*?account=sodlinken&password=11223344&mobile=13739554137&vip=0&recommend=
* @apiSuccess (200) {String} msg 信息
* @apiSuccess (200) {int} code 0 代表无错误 1代表有错误
* @apiSuccessExample {json} 返回样例:
*                {"code":"0","msg":"注册成功"}
*/

然后生成文档即可。

API Blueprint

官网 https://apiblueprint.org/
语法类似 markdown；在 https://apiblueprint.org/tools.html 页面搜索下载一个工具，比如 snowboard， https://github.com/bukalapak/snowboard，这个页面就是最好的文档：

# 参考 GitHub 页面给出的安装指引：linux下安装，安装最新版 v1.7.0 版
wget https://github.com/subosito/snowboard/releases/download/v1.7.0/snowboard-v1.7.0.linux-amd64.tar.gz
tar -zxvf snowboard-v1.7.0.linux-amd64.tar.gz
./snowboard -h

restdoc

官网
Spring 官方文档都是用 Spring REST Docs 生成的。restdoc通过单元测试生成snippets文件，snippets根据插件生成html等各种格式的文档。

入门

<dependency>
  <groupId>org.springframework.restdocs</groupId>
  <artifactId>spring-restdocs-mockmvc</artifactId>
  <scope>test</scope>
</dependency>

@RunWith(SpringRunner.class)
@WebMvcTest(DemoController.class)
// 开启配置生成snippets文件，并指定存放位置
@AutoConfigureRestDocs(outputDir = "target/snippets")
public class WebLayerTest {
	@Autowired
	private MockMvc mockMvc;
	
	@Test
	public void shouldReturnDefaultMessage() throws Exception {
	this.mockMvc.perform(get("/")).andDo(print()).andExpect(status().isOk())
		.andExpect(content().string(containsString("Hello World")))
		.andDo(document("demo"));
	}
}

单元测试执行成功后，生成6个adoc文档：

└── target
  └── snippets
    └── demo
      └── httpie-request.adoc
      └── curl-request.adoc
      └── http-request.adoc
      └── http-response.adoc
      └── request-body.adoc
      └── response-body.adoc

默认情况下，snippets是Asciidoctor格式的文件，包括request和response，httpie、curl、http三种请求模式。
转化为html文档
借助于asciidoctor-maven-plugin插件：

<plugin>
	<groupId>org.asciidoctor</groupId>
	<artifactId>asciidoctor-maven-plugin</artifactId>
	<executions>
		<execution>
			<id>generate-docs</id>
			<phase>prepare-package</phase>
			<goals>
				<goal>process-asciidoc</goal>
			</goals>
			<configuration>
				<sourceDocumentName>index.adoc</sourceDocumentName>
				<backend>html</backend>
				<attributes>
					<snippets>${project.build.directory}/snippets</snippets>
				</attributes>
			</configuration>
		</execution>
	</executions>
</plugin>

adoc的书写格式参考官网，创建文件src/main/asciidoc/index.adoc：

用 Spring REST Docs 构建文档
This is an example output for a service running at http://localhost:8080:
.request
include::{snippets}/demo/http-request.adoc[]
.response
include::{snippets}/demo/http-response.adoc[]

执行mvnw package命令生成HTML文档

参考

JApiDocs

衔接前后端开发的的工具，实现代码即文档，持续集成接口测试的小目标。在前后端协作中的一个问题，即使有完善的 API 文档，在接口没有开发出来之前，要进行接口的测试，只能本地或者通过一些平台（rap）去模拟接口生成相关数据，这对于前端开发人员来说也是一个额外的负担。
示例：
特性

深度集成 spring boot；
支持生成 Java 等语言的 Response 模型代码；
支持接口声明过时(@Deprecated)，方便的文档目录等；
支持自定义代码生成模板；
以一个 Controller 作为一组接口导出到一个 Html 文件中；
支持一般的 Java Web 工程，需要在相关方法添加额外的路由；

官网：
示例：https://yedaxia.me/play-apidocs/
GitHub：https://github.com/YeDaxia/JApiDocs

对比

API 工具	文档支持	语言支持	接口测试
swagger	功能强大，学习成本高，维护成本高	多语言	支持
apiDoc	学习成本一般，维护成本高	多语言	不支持
JApiDocs	代码即文档，学习和维护成本低	Java	支持发布到 RAP