M

MLOG

中文

探索 OpenAPI 规范 (OAS) 的强大功能。本指南涵盖了从核心概念和优势到实际示例以及 API 优先设计的未来等所有内容。

API 文档的演进：OpenAPI 规范综合指南

在当今高度互联的数字世界中，应用程序编程接口 (API) 是将我们的软件和服务编织在一起的无形丝线。它们是现代数字经济的引擎，支撑着从移动银行到社交媒体信息流的一切。但随着 API 数量的爆炸式增长，一个关键挑战也随之出现：开发人员、系统和组织如何能够有效且无歧义地进行沟通？我们如何确保在世界某地构建的 API 能够被另一地的服务无缝使用？

答案在于一种通用语言，一份人类和机器都能理解的、描述 API 功能的通用合约。这就是 OpenAPI 规范 (OAS) 的作用。OAS 不仅仅是文档，它还是一个用于设计、构建、记录和使用 RESTful API 的基础标准。本指南将带您深入了解 OpenAPI 规范，探索它是什么、为何重要，以及您如何利用它来构建更好、更具协作性的数字产品。

什么是 OpenAPI 规范？一种 API 的通用语言

其核心是，OpenAPI 规范是一个用于 RESTful API 的、与语言无关的标准化接口描述。它允许您在一个文件中定义 API 的整个结构，该文件通常用 YAML 或 JSON 编写。可以把它想象成一座建筑的详细蓝图；在任何施工开始之前，蓝图会勾勒出每个房间、每个门口和每个电源插座。同样，一个 OpenAPI 文档描述了：

简史：从 Swagger 到 OpenAPI

您可能听说过“Swagger”这个术语与 OpenAPI 交替使用。理解它们之间的关系很重要。该规范始于 2010 年，由 Reverb 的 Tony Tam 创建，当时名为 Swagger 规范。随着其广受欢迎，它于 2015 年被捐赠给 Linux 基金会，并更名为 OpenAPI 规范，从而在 OpenAPI 倡议（一个由谷歌、微软和 IBM 等行业领导者组成的联盟）的管理下，确立了其作为真正开放标准的地位。

如今，Swagger 指的是一套功能强大的开源和专业工具，它们与 OpenAPI 规范协同工作，例如用于生成交互式文档的 Swagger UI 和用于编写规范本身的 Swagger Editor。

OpenAPI 文档的核心组件

一个 OpenAPI 文档由一组特定的字段构成。虽然初看起来可能令人生畏，但它的组织结构是合乎逻辑的。让我们使用 YAML 来分解 OpenAPI 3.x 文档的关键构建块，因为它具有更好的人类可读性。

1. `openapi` 和 `info` 对象：基础信息

每个 OpenAPI 文档都以一个版本号和必要的元数据开始。

示例:


openapi: 3.0.3
info:
  title: 全球图书目录 API
  description: 一个用于访问全球图书目录的 API。
  version: 1.0.0
  contact:
    name: API 支持团队
    url: http://www.example.com/support
    email: support@example.com
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html

2. `servers` 数组：在哪里找到您的 API

servers 数组指定了您的 API 的基础 URL。您可以为不同的环境定义多个服务器，例如开发、预发布和生产环境。这使得工具可以轻松地在不同环境之间切换。

示例:


servers:
  - url: https://api.example.com/v1
    description: 生产服务器
  - url: https://staging-api.example.com/v1
    description: 预发布服务器

3. `paths` 对象：API 的核心

这是您定义 API 端点的地方。paths 对象包含了所有单独的 URL 路径。每个路径项接着描述了可以在该路径上执行的 HTTP 操作 (get, post, put, delete 等)。

在每个操作中，您可以定义如下细节：

4. `components` 对象：可重用的构建块

为了避免重复自己 (遵循 DRY 原则)，OpenAPI 提供了 components 对象。这是一个强大的功能，您可以在其中定义可重用的元素，并使用 $ref 指针在整个规范中引用它们。

5. `security` 对象：应用身份验证

一旦您在组件中定义了 securitySchemes，就可以使用 security 对象来应用它们。您可以将安全性全局应用于整个 API，也可以在每个操作的基础上应用，从而允许混合使用公共和受保护的端点。

为什么您的组织应该采用 OpenAPI：商业和技术优势

采用 OpenAPI 规范不仅仅是一个技术选择；它是一个战略决策，可以在整个软件开发生命周期中提高效率、协作和质量。

对于开发者：单一事实来源

对于产品经理和架构师：设计与治理

对于测试和 QA 团队：简化的验证

对于最终用户和合作伙伴：卓越的开发者体验 (DX)

实践指南：创建您的第一个 OpenAPI 文档

让我们通过为我们的“全球图书目录 API”创建一个基本的 OpenAPI 3.0 规范来将理论付诸实践。我们将使用 YAML 以获得更好的可读性。

第一步：定义基本信息和服务器

我们从元数据和生产服务器 URL 开始。


openapi: 3.0.3
info:
  title: 全球图书目录 API
  description: 一个用于访问全球图书目录的 API。
  version: 1.0.0
servers:
  - url: https://api.globalbooks.com/v1

第二步：在 `components` 中定义可重用的数据模型

在定义我们的端点之前，让我们为一个 `Book` 对象创建一个可重用的模式。这可以保持我们的设计整洁和一致。


components:
  schemas:
    Book:
      type: object
      properties:
        isbn:
          type: string
          description: 国际标准书号。
          example: '978-0321765723'
        title:
          type: string
          description: 书名。
          example: 'The C++ Programming Language'
        author:
          type: string
          description: 书的作者。
          example: 'Bjarne Stroustrup'
        publicationYear:
          type: integer
          description: 书的出版年份。
          example: 2013
      required:
        - isbn
        - title
        - author

第三步：在 `paths` 中定义端点

现在，我们将创建两个端点：一个用于获取图书列表，另一个用于通过其 ISBN 获取特定图书。

请注意 $ref: '#/components/schemas/Book' 的使用。这就是我们引用可重用 `Book` 模式的方式。


paths:
  /books:
    get:
      summary: 列出所有可用的图书
      description: 返回一个图书列表，可选择性地进行筛选。
      operationId: listBooks
      responses:
        '200':
          description: 一个成功的响应，带有一个图书数组。
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Book'

  /books/{isbn}:
    get:
      summary: 通过 ISBN 获取图书
      description: 返回由其 ISBN 标识的单本图书。
      operationId: getBookByIsbn
      parameters:
        - name: isbn
          in: path
          required: true
          description: 要检索的图书的 ISBN。
          schema:
            type: string
      responses:
        '200':
          description: 请求的图书。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Book'
        '404':
          description: 未找到具有指定 ISBN 的图书。

第四步：添加安全性

让我们用一个必须在标头中发送的简单 API 密钥来保护我们的 API。首先，我们在 `components` 中定义方案，然后全局应用它。


# 将此添加到 'components' 部分
components:
  # ... 之前的 schemas
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY

# 将此添加到文档的根级别
security:
  - ApiKeyAuth: []

第五步：验证和可视化

有了完整的 YAML 文件，您现在可以使用各种工具：

OpenAPI 生态系统：工具和技术

OAS 的强大功能被其庞大而成熟的工具生态系统所放大。无论您有什么需求，很可能都有相应的工具：

OpenAPI 的未来：OAS 3.1 及以后

OpenAPI 规范在不断发展。最新的主要版本 OAS 3.1 引入了几个重大的改进：

这些进步巩固了 OpenAPI 在现代、API 优先和事件驱动架构中作为核心产物的地位。

结论：现代开发的基石

OpenAPI 规范改变了我们对 API 的思考方式。它将 API 文档从一个令人畏惧、常常被忽视的事后工作，提升为一个驱动整个开发生命周期的战略性、活的文档。通过作为一份机器可读的合约，OAS 促进了协作，实现了强大的自动化，强制了-致性，并最终促成了更好、更可靠、更易于使用的 API 的创建。

无论您是开发人员、架构师、产品经理还是测试人员，拥抱 OpenAPI 规范都是掌握现代软件开发的关键一步。如果您还没有使用它，请考虑从您的下一个项目开始。首先定义合约，与您的团队分享，并在您的数字协作中解锁一个新的效率和清晰度水平。