API文档管理工具

2022-12-11 07:37:59

系统庞大之后，前后端分离开发，前端调用后端提供的接口，请求协议一般是 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 class="token keyword"><span class="hljs-function"><span class="hljs-keyword"><span class="hljs-function"><span class="hljs-keyword">private</span></span></span></span></span><span class="hljs-function"><span class="hljs-function"> ApiInfo </span></span><span class="token function"><span class="hljs-function"><span class="hljs-title"><span class="hljs-function"><span class="hljs-title">apiInfo</span></span></span></span></span><span class="token punctuation"><span class="hljs-function"><span class="hljs-params"><span class="hljs-function"><span class="hljs-params">(</span></span></span></span></span><span class="token punctuation"><span class="hljs-function"><span class="hljs-params"><span class="hljs-function"><span class="hljs-params">)</span></span></span></span></span><span class="hljs-function"><span class="hljs-function"> </span></span><span class="token punctuation">{</span>

    <span class="token keyword"><span class="hljs-keyword"><span class="hljs-keyword">return</span></span></span> <span class="token keyword"><span class="hljs-keyword"><span class="hljs-keyword">new</span></span></span> <span class="token class-name">ApiInfoBuilder</span><span class="token punctuation">(</span><span class="token punctuation">)</span>

            <span class="token punctuation">.</span><span class="token function">title</span><span class="token punctuation">(</span><span class="token string"><span class="hljs-string"><span class="hljs-string">"freemarker project RESTful APIs"</span></span></span><span class="token punctuation">)</span>

            <span class="token punctuation">.</span><span class="token function">description</span><span class="token punctuation">(</span><span class="token string"><span class="hljs-string"><span class="hljs-string">"this is freemarker app swagger-ui page"</span></span></span><span class="token punctuation">)</span>

            <span class="token punctuation">.</span><span class="token function">version</span><span class="token punctuation">(</span><span class="token string"><span class="hljs-string"><span class="hljs-string">"1.1"</span></span></span><span class="token punctuation">)</span>

            <span class="token punctuation">.</span><span class="token function">build</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span>

<span class="token punctuation">}</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 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

简介 & 特性

官方网站：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": "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/

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

参考：

Yapi

API文档自动生成工具apiDoc简介

原文地址：https://blog.csdn.net/lonelymanontheway/article/details/83177403

                                </div>

码农公寓