什么是 Open API Specification

作者: _扫地僧_ | 来源:发表于2024-08-03 09:23 被阅读0次

Open API Specification（简称 OAS），是一种标准化的语言，用于定义 RESTful API 的规范。RESTful API 是通过 HTTP 协议进行通信的接口，开放 API 则是让不同应用系统之间能够通过 API 进行交互。OAS 的出现，使得 API 的设计、文档编写和测试更加规范化和自动化。

OAS 在社区的支持下，逐渐成为描述 API 的事实标准。它的前身是 Swagger，虽然名称变了，但是它们的使命是一致的：通过统一的格式描述 API，避免了 API 文档混乱、版本不一致等问题。

为了更容易地理解 OAS，可以通过一个具体的例子来说明。

设想一个图书管理系统，这个系统允许用户添加、获取、更新和删除图书信息。我们将使用 Open API Specification 来描述这些操作。

示例：图书管理系统 API

openapi: 3.0.0
info:
  title: 图书管理系统 API
  description: 一个简单的图书管理系统的 API
  version: 1.0.0
servers:
  - url: http://api.books.com/v1
paths:
  /books:
    get:
      summary: 获取所有图书
      description: 返回系统中的所有图书
      responses:
        '200':
          description: 成功响应
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Book'
    post:
      summary: 添加一本图书
      description: 创建一个新的图书条目
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewBook'
      responses:
        '201':
          description: 创建成功
  /books/{id}:
    get:
      summary: 获取特定图书
      description: 根据 ID 获取图书详情
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 成功响应
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Book'
        '404':
          description: 图书未找到
    put:
      summary: 更新特定图书
      description: 根据 ID 更新图书信息
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewBook'
      responses:
        '200':
          description: 更新成功
        '404':
          description: 图书未找到
    delete:
      summary: 删除图书
      description: 根据 ID 删除图书条目
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: 删除成功
        '404':
          description: 图书未找到
components:
  schemas:
    Book:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        author:
          type: string
        publishedYear:
          type: integer
    NewBook:
      type: object
      properties:
        title:
          type: string
        author:
          type: string
        publishedYear:
          type: integer

这个例子展示了一个图书管理系统的 API。接下来，深入探讨其各个部分：

openapi: 3.0.0：
表示使用的是 Open API Specification 3.0.0 版本。
info：
包含了 API 的基础信息，如标题、描述、版本号等。
servers：
描述了 API 的服务器 URL。在这个例子中，http://api.books.com/v1 是 API 的访问地址。
paths：
定义了 API 路径及其具体操作。有两个主要路径：/books 和 /books/{id}。每个路径下定义了操作（GET、POST、PUT、DELETE 等），每种操作都有自己的描述、请求参数和响应信息。
components：
定义了 API 使用的复用模式。在这个例子中，有两个模式：Book 和 NewBook。Book 描述了完整的图书信息，而 NewBook 描述了新创建图书的信息。

让我们仔细看看 /books 路径下的操作：

GET /books：
该操作获取所有图书。响应是一个包含图书对象的数组，响应码是 200 表示成功。
POST /books：
该操作用于添加一本新图书。请求体需要包含新图书的信息，格式为 JSON。响应码 201 表示创建成功。

再看 /books/{id} 路径下的操作：

GET /books/{id}：
该操作获取特定图书的信息。请求参数 id 表示图书的唯一标识，响应码 200 表示成功，404 表示图书未找到。
PUT /books/{id}：
该操作更新特定图书的信息。请求参数 id 和请求体（新图书信息）是必须的，响应码 200 表示更新成功，404 表示图书未找到。
DELETE /books/{id}：
该操作删除特定图书。请求参数 id 是必须的，响应码 204 表示删除成功，404 表示图书未找到。

除了规范 API 的设计和文档外，OAS 还能帮助生成客户端和服务器代码，甚至可以自动化测试。API 的定义越详细，自动化的程度越高，开发和维护的效率也越高。

真实世界的应用：Twitter API

为了让这个概念更加具体，我们可以看看真实世界中如何应用 OAS。Twitter 提供了一个非常成熟的 API，可以帮助开发者访问 Twitter 的功能，比如发推文、读取用户时间线等。Twitter 的 API 有详细的文档，而且本身就是使用 Open API Specification 描述的。

比如，获取 Twitter 用户时间线的 API：

openapi: 3.0.0
info:
  title: Twitter API
  description: 这个 API 允许应用程序与 Twitter 的功能进行交互
  version: 2.0.0
servers:
  - url: https://api.twitter.com/2
paths:
  /users/{id}/tweets:
    get:
      summary: 获取用户时间线
      description: 返回指定用户的推文时间线
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            description: 用户的唯一标识
        - name: max_results
          in: query
          required: false
          schema:
            type: integer
            description: 返回的最大推文数量
      responses:
        '200':
          description: 成功响应
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Tweet'
        '404':
          description: 用户未找到
components:
  schemas:
    Tweet:
      type: object
      properties:
        id:
          type: string
        text:
          type: string
        created_at:
          type: string
          format: date-time

从这个示例中，我们可以看到 Twitter 是如何通过 OAS 描述其 API 的。无论是路径参数 id 还是 query 参数 max_results，都清楚地定义了它们的位置、是否必须以及数据类型。同时，响应部分通过引用模式 Tweet 来定义推文的结构。

事务性和一致性

另一个值得探讨的概念是事务性和一致性。对于像金融系统或者库存管理系统这类需要事务确保数据一致性的系统，API 的设计和规范尤为重要。

假设我们管理一个电子商务系统，其中一个 API 用于处理订单。订单系统需要确保在多个操作步骤中，数据的一致性和可靠性。我们可以借助 OAS 和事务管理技术，通过定义好每个步骤的 API 和处理逻辑，确保整个事务的完整性。

例子：订单管理系统

openapi: 3.0.0
info:
  title: 订单管理系统 API
  description: 这个 API 处理电子商务订单
  version: 1.0.0
servers:
  - url: http://api.orders.com/v1
paths:
  /orders:
    post:
      summary: 创建订单
      description: 创建一个新订单并开始事务
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewOrder'
      responses:
        '201':
          description: 创建成功，返回订单 ID
  /orders/{id}:
    put:
      summary: 更新订单状态
      description: 更新特定订单的状态以反映事务的几个步骤
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderStatus'
      responses:
        '200':
          description: 更新成功
        '404':
          description: 订单未找到
components:
  schemas:
    NewOrder:
      type: object
      properties:
        customerId:
          type: string
        items:
          type: array
          items:
            $ref: '#/components/schemas/OrderItem'
    OrderItem:
      type: object
      properties:
        productId:
          type: string
        quantity:
          type: integer
    OrderStatus:
      type: object
      properties:
        status:
          type: string
          enum: [pending, confirmed, shipped, delivered, canceled]

例如，一个新订单创建的流程可能包含以下步骤：

从客户账户中扣款。
减少库存。
通知仓库准备发货。
更新订单状态为 confirmed。

在这个过程中，我们需要确保每一步都成功才能进入下一步。如果某步骤失败，需要执行回滚操作以保持系统内数据的一致性。

OAS 使得各步骤的接口规范化，便于各模块之间的集成，同时也容易被测试和维护。通过这种方式，OAS 可以帮助确保复杂事务性操作的一致性和可靠性。

安全性

讨论 API 规约，安全性是一个绕不开的话题。OAS 提供了多种机制来描述和实现安全性。

在 OAS 中，我们可以定义安全需求，如 OAuth2、API Key 等。假设我们的图书管理系统需要用户登录，并使用 Bearer Token 进行身份验证：

openapi: 3.0.0
info:
  title: 安全的图书管理系统 API
  description: 这个 API 使用 Bearer Token 进行身份验证
  version: 1.0.0
servers:
  - url: http://api.securebooks.com/v1
paths:
  /books:
    get:
      summary: 获取所有图书
      security:
        - bearerAuth: []
      responses:
        '200':
          description: 成功响应
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Book'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT  # 可选，指定 JWT 格式
  schemas:
    Book:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        author:
          type: string
        publishedYear:
          type: integer

在这个示例中，securitySchemes 定义了 bearerAuth 作为认证方式，并指定在 GET /books 路径下的操作需要这种认证。通过这样的定义，我们可以确保只有通过身份验证的用户才能访问 API。

安全性不仅仅是身份验证，还有比如数据加密、输入校验、防止 CSRF 和 XSS 等多种手段。通过 OAS，可以更加清晰和详细地定义这些安全要求，使 API 开发和使用更加安全可信。

版本控制

API 的版本控制也是一个重要的概念。在实际应用中，API 需要不断演进和更新，但又必须保证旧版的兼容性。OAS 支持通过版本号来管理 API 的不同版本。

假设我们的图书管理系统从 1.0 版本升级到 2.0 版本，新版本添加了新的字段和路径。我们可以这样定义：

openapi: 3.0.0
info:
  title: 图书管理系统 API
  description: 图书管理系统的不同版本 API
  version: 2.0.0
servers:
  - url: http://api.books.com/v2
paths:
  /books:
    get:
      summary: 获取所有图书
      responses:
        '200':
          description: 成功响应
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Book'
  /books/{id}:
    get:
      summary: 获取特定图书
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 成功响应
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Book'
components:
  schemas:
    Book:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        author:
          type: string
        publishedYear:
          type: integer
        genre:  # 新增字段
          type: string

通过版本号和路径的区分，新老版本的 API 可以同时存在，保证了系统的兼容性和灵活性。这在实际开发中非常重要，可以避免由于 API 的变动导致的不可预见的问题。

总结

OAS 是一个强大的工具，用于描述 RESTful API 规范。它通过对 API 的详细描述，使得 API 的设计、文档编写、测试和使用更加规范化和自动化。通过具体的例子，如图书管理系统、Twitter API 和订单管理系统，可以清楚看到 OAS 在实际应用中的强大功能。不论是事务性、一致性、安全性还是版本控制，OAS 都提供了强大的支持，使 API 开发更加高效和可靠。

什么是 Open API Specification

示例：图书管理系统 API

真实世界的应用：Twitter API

事务性和一致性

安全性

版本控制

总结

相关文章

网友评论

延伸阅读

深度阅读

栏目导航

热点阅读