上圖分解了 OAS 設(shè)計(jì)的 API 契約中的各個(gè)部分。乍一看可能有點(diǎn)混亂，但讓我分解一下每個(gè)部分的含義及其用法。

信息

信息部分包含與 API 合同相關(guān)的元數(shù)據(jù)。此部分的必需部分是 API 的標(biāo)題、版本和說(shuō)明。此部分還可以包含其他字段，如聯(lián)系信息、許可信息和服務(wù)條款鏈接。本質(zhì)上，信息對(duì)象應(yīng)該為您的消費(fèi)者以及您的內(nèi)部開(kāi)發(fā)人員提供有關(guān)您的 API 功能的高級(jí)概述。

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

服務(wù)器

您的 API 是消費(fèi)者和服務(wù)器之間的契約。服務(wù)器對(duì)象可以通過(guò)其 URL 向您的客戶(hù)端提供有關(guān) API 服務(wù)器所在位置的信息。與規(guī)范的 2.0 版本不同，該版本僅允許您的 API 定義有一個(gè)服務(wù)器 URL，而 OAS 3.0 支持多個(gè)服務(wù)器。這很有用，因?yàn)樵诂F(xiàn)實(shí)世界中，API 存在于多個(gè)環(huán)境中，并且契約的業(yè)務(wù)邏輯可能會(huì)根據(jù)環(huán)境而變化。

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

安全

當(dāng)今數(shù)據(jù)敏感的世界中的每個(gè) API 都需要一定程度的安全性。OpenAPI 描述格式支持各種身份驗(yàn)證和授權(quán)方案，以減少未知、未注冊(cè)用戶(hù)訪問(wèn) API。OpenAPI 支持：

HTTP 身份驗(yàn)證方案
標(biāo)頭、Cookie 或查詢(xún)字符串中的 API 密鑰
OAuth2
開(kāi)放ID

在 API 設(shè)計(jì)中實(shí)現(xiàn)安全性有兩個(gè)步驟。第一步是定義安全性實(shí)現(xiàn)，第二步是調(diào)用它們。本節(jié)中定義的 Security 對(duì)象用于調(diào)用實(shí)際的安全性定義。定義安全性實(shí)現(xiàn)是在“組件”部分中完成的，本文后面將詳細(xì)介紹。

這是安全對(duì)象的一個(gè)??例子：

security:



- ApiKeyAuth: []



- OAuth2:



- read



- write



components:



ApiKeyAuth:



type: apiKey



in: header



name: X-API-Key

在上面的例子中，ApiKeyAuth 在 Security 對(duì)象下被調(diào)用，但該對(duì)象的實(shí)際定義應(yīng)該在components 對(duì)象下完成。

路徑

本部分展示了 API 公開(kāi)的各種端點(diǎn)以及相應(yīng)的 HTTP 方法。每種方法下還詳細(xì)介紹了實(shí)際的請(qǐng)求-響應(yīng)周期。請(qǐng)求由 Parameter 對(duì)象描述，響應(yīng)由 Responses 對(duì)象描述。

參數(shù)

參數(shù)是請(qǐng)求中的可變部分。使用 OAS 3.0 可以指定四種類(lèi)型的參數(shù)：

路徑參數(shù)，例如 /users/{id}
查詢(xún)參數(shù)，例如 /users?role=admin
標(biāo)頭參數(shù)，例如 X-MyHeader: Value
cookie 參數(shù)，這些參數(shù)在 Cookie 頭中傳遞，例如 Cookie: debug=0; csrftoken=BUSe35dohU3O1MZvDCU

響應(yīng)

響應(yīng)是請(qǐng)求后返回的對(duì)象。每個(gè)響應(yīng)都由其 HTTP 狀態(tài)代碼和返回的數(shù)據(jù)定義。使用的 HTTP 狀態(tài)代碼定義請(qǐng)求是成功還是失敗。要查看 HTTP 狀態(tài)代碼列表，請(qǐng)閱讀此處。

這是一個(gè)簡(jiǎn)單響應(yīng)的示例：

responses:



200:



description: Successful Response



content:



text/plain:



schema:



type: string



example: Example string is here

組件

隨著您向 API 公開(kāi)更多資源和操作，合同可能會(huì)變得非常長(zhǎng)。您的 API 可能會(huì)在許多不同的路徑和操作中重復(fù)大量現(xiàn)有參數(shù)或響應(yīng)描述，每次重寫(xiě)它們都容易導(dǎo)致描述不一致，并且可能非常耗時(shí)。

組件對(duì)象可以保存 API 設(shè)計(jì)的一組可重用對(duì)象。可重用對(duì)象可以是架構(gòu)、響應(yīng)、參數(shù)、示例等。然后可以在任何路徑項(xiàng)中引用確切的可重用組件。

以下是組件對(duì)象的一個(gè)??示例：

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

外部文檔

提供任何有助于簡(jiǎn)化使用和與 API 集成的附加信息始終是一個(gè)好主意。OAS 3.0 允許您引用外部文檔。

Description: Additional info can be found here



url: http://info.here.com

標(biāo)簽

標(biāo)簽是用于對(duì)各種操作進(jìn)行分組的友好類(lèi)別。這允許 API 的消費(fèi)者更好地細(xì)分和識(shí)別他們想要使用 API 做什么。這些標(biāo)簽也可以由集成或讀取 OAS 的其他第三方工具處理。

使用 tags 對(duì)象可以自動(dòng)將標(biāo)簽添加到每個(gè)路徑操作。通過(guò)在 API 定義的根級(jí)別中添加可選的 tags 部分，您可以更好地描述每個(gè)標(biāo)簽的含義。

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

當(dāng)然，這只是對(duì)與 OpenAPI 設(shè)計(jì)的 API 相關(guān)的各個(gè)部分的一般概述。設(shè)計(jì)是主觀的，雖然 OAS 為您提供了描述 API 所需的規(guī)則和項(xiàng)目，但如何使用它們有效地傳達(dá) API 的價(jià)值才是優(yōu)秀設(shè)計(jì)的關(guān)鍵。我過(guò)去曾介紹過(guò) API 設(shè)計(jì)的良好實(shí)踐，

適合 API 設(shè)計(jì)的正確工具

設(shè)計(jì)可能是 API 生命周期中最重要的方面之一，因此需要專(zhuān)用工具。Swagger的 OpenAPI 編輯器是開(kāi)始 API 設(shè)計(jì)流程的絕佳方式。它簡(jiǎn)潔、高效，并配備了許多功能，可幫助您開(kāi)箱即用地設(shè)計(jì) RESTful 接口。

該編輯器可在任何開(kāi)發(fā)環(huán)境中運(yùn)行，無(wú)論是本地還是網(wǎng)絡(luò)
在編寫(xiě)語(yǔ)法時(shí)，通過(guò)簡(jiǎn)潔的反饋和錯(cuò)誤處理來(lái)驗(yàn)證語(yǔ)法是否符合 OpenAPI 要求
以可視化方式呈現(xiàn)您的 API 規(guī)范，并在定義 API 的同時(shí)與其進(jìn)行交互

原文鏈接：OpenAPI-Driven API Design