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 定义的 OAS 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 服务器位置的信息。与仅允许 API 定义具有一个服务器 URL 的 2.0 版本规范不同，OAS 3.0 支持多个服务器。这很有用，因为在现实世界中，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 设计中实现安全性有两个步骤。第一步是定义安全实现，第二步是调用它们。本节中定义的 Security 对象用于调用实际的安全定义。安全实现的定义在 Components 部分中完成，该部分将在本文后面详细介绍。

这是 Security 对象的一个示例

security

- ApiKeyAuth: []

- OAuth2

- read

- write

components

ApiKeyAuth

type: apiKey

in: header

name: X-API-Key

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

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

路径

此部分显示您的 API 公开的各种端点以及相应的 HTTP 方法。此外，实际的请求-响应周期也在每个方法下详细说明。请求由参数对象描述，响应由响应对象描述。

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

参数

参数是请求的可变部分。您可以使用 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 设计的可重用对象。可重用对象可以是模式、响应、参数、示例等等。然后可以在任何路径项中引用精确的可重用组件。

这是一个组件对象的示例

路径

/pet

get

summary: 获取所有宠物

responses

'200':

description: 所有宠物列表

content

application/json

schema

type: array

items

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

components

模式

Pet

type: object

属性

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 设计的正确工具