OpenAPI 驱动的 API 设计

Keshav Vasudevan

2018 年 4 月 24 日

在我之前的帖子中，我详细阐述了使用 OpenAPI 规范 (OAS) 进行定义驱动开发的重要性，并承诺将发布更多文章，详细说明 OpenAPI 规范如何帮助您 API 生命周期的各个方面。

本系列的第二篇文章将深入探讨 OAS 如何在 API 生命周期的第一阶段：API 设计中为您提供帮助。

什么是 API 设计？

好的设计是纪念碑成为奇迹、产品变得伟大的原因。从埃菲尔铁塔等纪念碑，到这些酷炫的吸管等产品，设计都可以成为出色可用性和广泛采用的基石。

在 API 的世界中，设计可以被认为是建模服务器和客户端之间的契约。在之前的一篇文章中，我给出了 API 设计的以下定义：

“设计 API 意味着提供一个有效的接口，帮助 API 消费者更好地理解、使用和集成它们，同时帮助您有效地维护它。每个产品都需要一份使用手册，您的 API 也不例外。”

原始“Swagger”规范的创建者 Tony Tam 解释说，设计 API 涉及 “为失败做计划”。API 契约帮助内部和外部利益相关者了解如何操作，以及他们如何更好地协同工作来构建出色的 API。

使用 OAS 3.0 设计 API

OpenAPI 规范是设计 API 最知名的方法之一。OAS 指定了描述 API 接口所需的规则和语法。在撰写本文时，OAS 已发布第三个版本。OAS 不断发展，以满足现代 API 团队的需求，并持续引入更新，使规范更易于使用，更易于人类和计算机理解。以下是使用 OAS 3.0 定义的 API 的一般概述

上图分解了 OAS 设计的 API 契约中的各个部分。乍一看可能令人困惑，但让我来分解每个部分的含义以及如何使用它们。

信息

信息部分包含与 API 契约相关的元数据。此部分的必填字段是 API 的标题、版本和描述。此部分还可以包含其他字段，如联系信息、许可信息和服务条款链接。本质上，信息对象应该向您的消费者以及内部开发人员提供 API 功能的高级概述。

openapi: 3.0.0

info

title: 简单宠物商店

version: 1.0.0

description: 这是一个宠物商店的示例服务器。

termsOfService: http://example.com/terms/

contact

name: API 博客作者

email: [email protected]

url: http://example.com/support

license

name: Apache 2.0

url: https://apache.ac.cn/licenses/LICENSE-2.0.html

在此处阅读完整文档。

服务器

您的 API 是消费者和您的服务器之间的契约。服务器对象可以通过其 URL 向您的客户端提供 API 服务器所在位置的信息。与规范的 2.0 版本不同，OAS 3.0 支持多个服务器，而 2.0 版本只允许您的 API 定义有一个服务器 URL。这很有用，因为在现实世界中，API 存在于多个环境中，并且契约的业务逻辑可能根据环境而变化。

此部分示例如下 -

servers

- url: http://production.example.com/v1

description: 生产服务器

- url: http://staging.example.com

description: 用于测试的暂存服务器

在此处阅读完整文档。

安全

在当今数据敏感的世界中，每个 API 都需要一定程度的安全性。OpenAPI 描述格式支持各种认证和授权方案，以阻止未知、未注册的用户访问 API。OpenAPI 支持

HTTP 认证方案
请求头、Cookie 或查询字符串中的 API 密钥
OAuth2
OpenID

在 API 设计中实施安全措施有两个步骤。第一步是定义安全实现，第二步是调用它们。本节中定义的安全对象用于调用实际的安全定义。安全实现是在组件 (Components) 部分中定义的，本文后面会详细介绍。

这是安全对象的示例

security

- ApiKeyAuth: []

- OAuth2

- read

- write

components

ApiKeyAuth

type: apiKey

in: header

name: X-API-Key

在上述示例中，ApiKeyAuth 在 Security 对象下被调用，尽管该对象的实际定义应在 components 对象下完成。

在此处阅读有关安全对象的更多信息。

路径

本节展示了您的 API 公开的各种端点以及相应的 HTTP 方法。实际的请求-响应循环也在每个方法下进行了详细说明。请求由 Parameter (参数) 对象描述，响应由 Responses (响应) 对象描述。

您可以在此处阅读有关路径和操作的更多信息。

参数

参数是请求的可变部分。您可以使用 OAS 3.0 指定四种类型的参数：

路径参数，例如 /users/{id}
查询参数，例如 /users?role=admin
请求头参数，例如 X-MyHeader: Value
Cookie 参数，通过 Cookie 头传递，例如 Cookie: debug=0; csrftoken=BUSe35dohU3O1MZvDCU

响应

响应是请求返回的对象。每个响应都由其 HTTP 状态码和返回数据定义。所使用的 HTTP 状态码定义了请求是成功还是失败。要查看 HTTP 状态码列表，请在此处阅读。

以下是一个简单响应的示例

responses

200:

description: 成功响应

content

text/plain

schema

type: string

example: 示例字符串在此

在此处阅读有关响应的更多信息。

组件

随着您向 API 公开更多资源和操作，契约可能会变得非常冗长。您的 API 可能会在许多不同的路径和操作中重复大量的现有参数或响应描述，每次重写它们容易导致描述不一致，并且非常耗时。

组件对象可以包含一组 API 设计中可重用的对象。可重用对象可以是模式 (schemas)、响应 (responses)、参数 (parameters)、示例 (examples) 等。然后可以在任何路径项中引用确切的可重用组件。

以下是组件对象的示例

paths

/pet

get

summary: 获取所有宠物

responses

'200':

description: 所有宠物列表

content

application/json

schema

type: array

items

$ref: '#/components/schemas/Pet”

components

schemas

Pet

type: object

properties

id

type: integer

example: 65

name

type: string

example: doggo

age

type: integer

example: 4

在此处阅读有关组件的更多信息。

外部文档

您能提供的任何额外信息，只要能方便 API 的使用和集成，都是个好主意。OAS 3.0 允许您引用外部文档。

Description: 更多信息可在此处找到

url: http://info.here.com

当然，这只是对 OpenAPI 设计的 API 相关各个部分的概述。设计是主观的，虽然 OAS 提供了描述 API 所需的规则和项目，但如何有效地利用它们来传达 API 的价值，才是实现出色设计的关键。我过去曾介绍过 API 设计的最佳实践，因此请务必查看并分享您的想法。

如果您想了解 OAS 3.0 相较于 2.0 有哪些新功能，请查看此录制培训；如果您只想了解如何开始使用 OAS，则可以随时参考此视频。

API 设计的正确工具

设计可能是 API 生命周期中最重要的方面之一，因此需要一个专用工具。Swagger 的 OpenAPI 编辑器是启动 API 设计过程的好方法。它简洁、高效，并配备了许多功能，可帮助您即刻设计 RESTful 接口。

该编辑器可在任何开发环境中运行，无论是在本地还是在 Web 上
在编写时验证您的语法是否符合 OpenAPI 规范，并提供简洁的反馈和错误处理
在定义 API 时，以可视化方式渲染您的 API 规范并与 API 进行交互

如果您想与他人协作进行 API 设计，可以随时尝试 SwaggerHub。SwaggerHub 是一个 API 开发平台，供团队以一致和标准化的方式设计 API。Swagger 工具生态系统与 OAS 相结合，可以将您的 API 设计水平提升到一个新的高度。

感谢阅读！正在寻找更多 API 资源？订阅 Swagger 新闻邮件。每月接收一封电子邮件，内含我们最佳的 API 文章、培训、教程等。 订阅

OpenAPI 驱动的 API 设计

什么是 API 设计？

使用 OAS 3.0 设计 API

信息

服务器

安全

路径

参数

响应

组件

外部文档

标签

API 设计的正确工具