使用 OpenAPI 设计 RESTful API (一)

0x00. OpenAPI 简介

在之前的文章 Restful API 设计指导中，我介绍了如何设计 Restful API。随着前后端的分离以及软件架构的复杂化，你是否也遇到过以下的一个或者多个问题呢？

API 的设计和实现并非同一个人。无论是在大型互联网架构中还是复杂的软件开发中，API 的设计往往是有架构师、资深工程师、PM 等这些经验丰富的人负责。一旦设计完成，才将具体的开发任务分配给相应的 API 开发工程师。
API 有完整的测试。越是复杂的产品，对产品的质量有越高的要求，一般而言会有专门的测试团队对 API 进行完整的自动化测试。
前端开发工程师（或者 API 的调用方）和 API 工程师协同开发，因此前端工程师需要 Mock API 以解除对 API 开发进度的依赖。

为了解决以上问题中，至少需要保证两点：

API 的设计优先。
API 的设计结果需要在架构师、 API 开发工程师、测试工程师和前端工程师中清晰准确的传递。

OpenAPI 规范通过定义一种 API 规范旨在解决 API 的设计、开发、消费之间的信息传递问题。

The OpenAPI Specification, originally known as the Swagger Specification, is a specification) for machine-readable interface) files for describing, producing, consuming, and visualizing RESTful web services.[1] Originally part of the Swagger) framework, it became a separate project in 2016, overseen by the OpenAPI Initiative, an open-source collaboration project of the Linux Foundation.[2] Swagger and some other tools can generate code, documentation and test cases given an interface file.

– from Wikipedia

OpenAPI 规范截止目前共发布了 3 个大版本，目前主要使用的分别是 OpenAPI 3 和 Swagger 2，他们之间跟属性的差别如下：

API 的定义支持 YAML 格式和 JSON 格式。以官方提供的基于 Swagger 2.0 的 Petstore API 设计方案为例，

Swagger 2.0 版本常用的根属性（Fixed Field）有：

属性名	取值类型	描述
swagger	`string`	定义 OpenAPI 规范的版本号， v2 版本取值必须是`"2.0"`.
info	Info Object	API 的元数据信息。包括开发者信息，API 的概述，API 版本和版权等信息。
host	`string`	定义 API 的访问域名。
basePath	`string`	访问 API 时将此值做为 API 的前缀路径。
schemes	[`string`]	API 支持的通信协议，包括 `"http"`, `"https"`, `"ws"`, `"wss"` 等一种或多种。
paths	Paths Object	每个 API 的具体定义。定义中包括 API 的端点（endpoint），参数类型，返回值类型。每个 API 端点的定义中，又以 API 的调用方法分组。
definitions	Definitions Object	定义一个数据结构，一般将公用的数据模型定义在此处以供 API 的定义直接引用。

更多属性及其定义可以查看官方文档 OpenAPI V2.0。

0x01. Swagger

Swagger 是 OpenAPI 的实现，它提供了 API 设计、API 测试、可视化 API 的定义和 Mock API 数据等诸多功能。

Swagger 提供了一些开源组件，这些组件都是开源的。Swagger 官方把他们被集成到了 Swagger Hub 中供我们直接在线上使用，当然我们也可以单独将这些组件部署在我们的开发环境中：

Swagger Codegen

Swagger Codegen 可以将 API 的 OpenAPI 定义翻译成各种格式的接口文档，也可以生成各种编程语言的 SDK 代码。

Swagger Codegen can simplify your build process by generating server stubs and client SDKs for any API, defined with the OpenAPI (formerly known as Swagger) specification, so your team can focus better on your API’s implementation and adoption.
Swagger Editor

Swagger Editor 提供在线编辑，设计 API 的功能。

Design, describe, and document your API on the first open source editor fully dedicated to OpenAPI-based APIs. The Swagger Editor is an easy way to get started with the OpenAPI Specification (formerly known as Swagger), with support for Swagger 2.0 and OpenAPI 3.0.
Swagger UI

Swagger UI 将 API 的设计可视化，让 API 的消费者更加容易阅读 API 的定义和使用 API。

Swagger UI allows anyone — be it your development team or your end consumers — to visualize and interact with the API’s resources without having any of the implementation logic in place. It’s automatically generated from your OpenAPI (formerly known as Swagger) Specification, with the visual documentation making it easy for back end implementation and client side consumption.

0x02. 使用 Swagger 设计 API

2.0 初识 Swagger Editor

使用 Swagger 设计 API，首先要打开 Swagger Hub 或者 Swagger Editor。打开 Swagger Editor 后，默认会载入 Petstore 的 API 定义，

其中 Swagger Editor 集成了 Swagger UI，如右侧所示。左侧的区域 1 为 API 定义代码编辑器，右侧区域 2 为 API 的描述信息展示区，右侧区域 3 为 API 的定义可视化区，右侧区域 4 则为 API 引用的数据模型定义的可视化区。

在区域 2 中点击具体的某个 API，以 POST /user 为例，可以看到更多的 API 定义信息,

2.1 设计 GET /user 接口

设计一个 GET /user 的接口用于返回用户列表，在 /user 下添加 get 方法，并有如下定义：

/user:
  get:
    tags:
    - "user"
    summary: "Get users with filltering"
    operationId: "getUser"
    consumes:
    - "application/json"
    produces:
    - "application/json"
    responses:
      200:
        description: "successful operation"
        schema:
          type: "array"
          items:
            $ref: "#/definitions/User"
      400:
        description: "Invalid query parameters"

可视化的 GET /user 接口如下：

2.3 添加过滤参数

为了让 GET /user 接口支持分页查询，我们需要定义两个过滤参数 skip 和 limit。这两个参数是携带在请求的 URL 中的，因此我们需要为 GET 请求添加如下的查询参数定义：

parameters:
- in: "query"
  name: "skip"
  type: "integer"
  description: "Skip number of users"
- in: "query"
  name: "limit"
  type: "integer"
  description: "Limit number of users"

其中 in: "query" 表示该参数位于请求的 URL 中，除此之外，参数还可以携带在请求的头部或者实体中，分别取值 in: "header" 和 in: "body"。

至此，我们就完成了一个 API 的设计。我们只需要将 API 的设计描述文件发送给各个角色的人员，大家行可以围绕着下如下开发流程进行并行开发。

综上所述，本文主要介绍了基于 OpenAPI 协议和 Swagger 工具的 API 设计和开发。后续将以 NodeJS 为例，介绍 Swagger 如何集成到 API 的开发环境中，以及它是如何为 API 开发保驾护航的，敬请期待。