什么是 OpenAPI，OpenAPI 规范基本信息

作为一名开发者，往往需要编写程序的 API 文档，尤其是 Web 后端开发者，在跟前端对接 HTTP 接口的时候，一个好的 API 文档能够大大提高协作效率，降低沟通成本，本文就来聊聊如何使用 OpenAPI 构建 HTTP 接口文档。

OpenAPI

什么是 OpenAPI

OpenAPI 是规范化描述 API 领域应用最广泛的行业标准，由 OpenAPI Initiative(OAI) 定义并维护，同时也是 Linux 基金会下的一个开源项目。通常我们所说的 OpenAPI 全称应该是 OpenAPI Specification(OpenAPI 规范，简称 OSA)，它使用规定的格式来描述 HTTP RESTful API 的定义，以此来规范 RESTful 服务开发过程。使用 JSON 或 YAML 来描述一个标准的、与编程语言无关的 HTTP API 接口。OpenAPI 规范最初基于 SmartBear Software 在 2015 年捐赠的 Swagger 规范演变而来，目前最新的版本是 v3.1.0。

简单来说，OpenAPI 就是用来定义 HTTP 接口文档的一种规范，大家都按照同一套规范来编写接口文档，能够极大的减少沟通成本。

OpenAPI 规范基本信息

OpenAPI 规范内容包含非常多的细节，本文无法一一讲解，这里仅介绍常见的基本信息，以 YAML 为例进行说明。YAML 是 JSON 的超集，在 OpenAPI 规范中定义的所有语法，两者之间是可以互相转换的，如果手动编写，建议编写 YAML 格式，更为易读。

OpenAPI 文档编写在一个 .json 或 .yaml 中，推荐将其命名为 openapi.json 或 openapi.yaml，OpenAPI 文档其实就是一个单一的 JSON 对象，其中包含符合 OpenAPI 规范中定义的结构字段。

OpenAPI 规范基本信息如下：

字段名	类型	描述
openapi	string	必选，必须是 OpenAPI 已发布的合法版本，如 3.0.1。
info	object	必选，此字段提供 API 相关的元数据（如描述、作者和联系信息）。
servers	array[object]	这是一个 Server 对象的数组，提供到服务器的连接信息。
paths	object	必选，API 提供的可用的路径和操作。
components	object	一个包含多种结构的元素，可复用组件。
security	array	声明 API 使用的安全认证机制，目前支持 HTTP Basic Auth、HTTP Bearer Auth、ApiKey Auth 以及 OAuth2。
tags	array	提供标签可以为 API 归类，每个标签名都应该是唯一的。
externalDocs	object	附加的文档，可以通过扩展属性来扩展文档。

一个 YAML 格式的 OpenAPI 文档示例如下：

openapi: 3.1.0
info:
  title: Tic Tac Toe
  description: |
    This API allows writing down marks on a Tic Tac Toe board
    and requesting the state of the board or of individual squares.
  version: 1.0.0 # 此为 API 接口文档版本，与 openapi 版本无关
tags:
  - name: Gameplay
paths:
  # Whole board operations
  /board:
    get:
      summary: Get the whole board
      description: Retrieves the current state of the board and the winner.
      tags:
        - Gameplay
      operationId: get-board
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/status"

  # Single square operations
  /board/{row}/{column}:
    parameters:
      - $ref: "#/components/parameters/rowParam"
      - $ref: "#/components/parameters/columnParam"
    get:
      summary: Get a single board square
      description: Retrieves the requested square.
      tags:
        - Gameplay
      operationId: get-square
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/mark"
        "400":
          description: The provided parameters are incorrect
          content:
            text/html:
              schema:
                $ref: "#/components/schemas/errorMessage"
              example: "Illegal coordinates"
...

以上示例完整文档在此，具体语法我就不在这里介绍了。如果你开发过 API 接口，相信能看懂文档大部分内容所代表的含义。不必完全掌握其语法，这并不会对阅读本文接下来的内容造成困扰，因为稍后我会介绍如何通过代码注释的方式自动生成此文档。

如果你想手动编写 OpenAPI 文档，那么我还是推荐你阅读下 OpenAPI 规范，这里有一份中文版的规范。阅读规范是一个比较枯燥的过程，如果你没有耐心读完，强烈建议阅读 OpenAPI 规范入门，相较于完整版的规范要精简得多，并且讲解更加易于理解。

另外还推荐访问 OpenAPI Map 网站来掌握 OpenAPI 规范，该网站以思维导图的形式展现规范的格式以及说明。