OpenAPI入门指南

OpenAPI 入门指南

OpenAPI 是什么

OpenAPI 规范，也就是 OAS，它与编程语言无关。这使得计算机和人类用户都能够识别和理解服务功能，而无需额外的文档、访问源代码或检查网络流量。OAS 消除了调用服务的猜测，类似于接口描述简化较低级别编程的方式。使用 OpenAPI，您可以快速发现 API 是如何工作的。OpenAPI 的 API 规范通常是用 YAML 或 JSON 编写的。

API 优先开发

我们在开发一个项目的时候，最好的做法就是先出接口文档，接口文档涉及了几个很重要的点：

接口的规则
接口的请求、响应

只有先出了接口文档，才能很好地保证前端、后端的协同开发统一性、规范性。我觉得 API 文档应该是整个代码开发的基础，通过制定的接口规则来进行交互编写，才更加稳定高效，也就是所谓的 API-Frist。

OpenAPI 规范

OpenAPI 的规范，一开始就是 Swagger 的规范，只不过经过了 Reverb Technologies 和 SmartBear 等几个公司多年的维护，OpenAPI 开始有了属于自己的规范，更详细可以看：OpenAPI 规范（中文版）

OpenAPI 的规范是与语言无关的，这样才能保证 OpenAPI 规范的通用性,普及性，OpenAPI 一般通过 JSON 或 YAML 这种通用型语言来进行导入导出，保证通用性。

OpenAPI 3.0.1 的版本文档，OpenAPI 文档中的对象包括：

对象	描述	是否必需
OpenAPI Object	整个 OpenAPI 文档对象	是
Info Object	描述文档信息的对象	是
Paths Object	描述接口路径的对象	是
Components Object	描述组件的对象	否
Tag Object	对路径进行分组的对象	否
ExternalDocs Object	拓展文档对象	否
Security Object	安全性对象	否
Servers Object	描述服务端的对象	否

比如以下是一个 Info Object 的示例：

openapi: 3.0.1
servers:
  # Added by API Auto Mocking Plugin
  - description: SwaggerHub API Auto Mocking
    url: https://virtserver.swaggerhub.com/xxx/books/1.0.0
info:
  version: "1.0.0"
  title: home-iot-api
  description: The API for the EatBacon IOT project

比如以下是一个 Paths Object 的示例：

paths:
  /devices:
    get:
      tags:
        - Device
      description: returns all registered devices
      operationId: getDevices
      parameters:
        - in: query
          name: skip
          description: number of records to skip
          schema:
            type: integer
            format: int32
        - in: query
          name: limit
          description: max number of records to return
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: All the devices
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                  format: uri
                  example: 'http://10.0.0.225:8080'