API文档管理工具

系统庞大之后，前后端分离开发，前端调用后端提供的接口，请求协议一般是 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();
    }

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

​​
​​

​​}​​

​​
​​

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 [e-mail]: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

简介 & 特性

官方网站：​​https://yapi.ymfe.org/index.html​​

Github地址：​​https://github.com/YMFE/yapi​​

YApi 由 YMFE 开源，旨在为开发、产品、测试人员提供更优雅的接口管理服务，可以帮助开发者轻松创建、发布、维护 API。

特性

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

YMFE——去哪儿大前端团队 & 移动架构组，由FE，iOS和Android工程师共同组成。

安装

使用 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": "[e-mail]",
  "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/​​

apiDoc是一个非常轻量级的，适用于几乎所有流行语言的，针对Restful API的文档自动生成工具。文档写在注释里面，apiDoc基于NodeJS实现，提供历史版本比较功能。

安装：​​npm install apidoc -g​​

文档生成：​​apidoc -i src -o dest​​，该命令从当前工作目录的src子目录下读取所有代码文件，并从中抽取apiDoc的文档注释，然后生成HTML格式的文档，并保存在dest子目录下。

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

restdocs 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