API文档管理工具

系统庞大之后，前后端分离开发，前端调用后端提供的接口，请求协议一般是 HTTP，数据格式是 JSON。后台只负责数据的提供和计算，而完全不处理展现；而前端则负责拿到数据，组织数据并展现的工作。这样结构清晰，关注点分离，前后端会变得相对独立并松耦合。但是这样带来的一个问题就是，前端可能需要拿到后端的数据之后，才能开始开发工作，等前端开发完成之后，然后再与后端一起联调。耗时不说，如果业务的需求更改，后端接口变更，怎么快速便捷告知前端的开发人员？还有其他问题……
此时就需要一个在线接口文档平台/工具，提供接口的请求参数和响应参数结构以及真实数据，方便联调；

swagger

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

Swagger提供的工具主要有：

• Swagger Core：Swagger-core 是 Swagger的Java 实现，是整个swagger工具的核心实现。
• Swagger Codegen：提供根据swagger的接口定义文件(yaml形式)，直接生产相应的代码，以一种命令行工具的形式
• Swagger Editro：使用 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

使用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的属性描述。

Swagger Editor

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

git clone [email protected]: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 的吐槽：
耦合性太强，重复的注解信息？

restdocs

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": "[email protected]",
  "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 &

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

apidocjs

http://apidocjs.com/

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	功能强大，学习成本高，维护成本高	多语言	支持
apidocjs	学习成本一般，维护成本高	多语言	不支持
JApiDocs	代码即文档，学习和维护成本低	Java	支持发布到 RAP

参考：
Yapi