什么是 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: Simple Pet Store



version: 1.0.0



description: This is a sample server for a pet store.



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



contact:



name: API Blogger



email: support@example.com



url: http://example.com/support



license:



name: Apache 2.0



url: http://www.apache.org/licenses/LICENSE-2.0.html

服务器

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

An example of this section is below -



servers:



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



description: Production server



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



description: Staging server for testing

安全

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

HTTP 身份验证方案
标头、Cookie 或查询字符串中的 API 密钥
OAuth2
开放ID

在 API 设计中实现安全性有两个步骤。第一步是定义安全性实现，第二步是调用它们。本节中定义的 Security 对象用于调用实际的安全性定义。定义安全性实现是在“组件”部分中完成的，本文后面将详细介绍。

这是安全对象的一个例子：

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: Successful Response



content:



text/plain:



schema:



type: string



example: Example string is here

组件

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

组件对象可以保存 API 设计的一组可重用对象。可重用对象可以是架构、响应、参数、示例等。然后可以在任何路径项中引用确切的可重用组件。

以下是组件对象的一个示例：

paths:



/pet:



get:



summary: Get all pets



responses:



'200':



description: List of all pets



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: Additional info can be found here



url: http://info.here.com

paths:



/pet/findByStatus:



get:



summary: Finds pets by Status



tags:



- pets



...



/pet:



post:



summary: Adds a new pet to the store



tags:



- pets



...



/store/inventory:



get:



summary: Returns pet inventories



tags:



- store



...



tags:



- name: pets



description: Everything about your Pets



externalDocs:



url: http://docs.my-api.com/pet-operations.html



- name: store



description: Access to Petstore orders



externalDocs:



url: http://docs.my-api.com/store-orders.html