探索頂級PDF水印API：PDFBlocks（2024年更新）
你可能也喜歡這些API文章!
上圖分解了 OAS 設計的 API 契約中的各個部分。乍一看可能有點混亂，但讓我分解一下每個部分的含義及其用法。
信息部分包含與 API 合同相關(guān)的元數(shù)據(jù)。此部分的必需部分是 API 的標題、版本和說明。此部分還可以包含其他字段，如聯(lián)系信息、許可信息和服務條款鏈接。本質(zhì)上，信息對象應該為您的消費者以及您的內(nèi)部開發(fā)人員提供有關(guān)您的 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 向您的客戶端提供有關(guān) API 服務器所在位置的信息。與規(guī)范的 2.0 版本不同，該版本僅允許您的 API 定義有一個服務器 URL，而 OAS 3.0 支持多個服務器。這很有用，因為在現(xiàn)實世界中，API 存在于多個環(huán)境中，并且契約的業(yè)務邏輯可能會根據(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當今數(shù)據(jù)敏感的世界中的每個 API 都需要一定程度的安全性。OpenAPI 描述格式支持各種身份驗證和授權(quán)方案，以減少未知、未注冊用戶訪問 API。OpenAPI 支持：
在 API 設計中實現(xiàn)安全性有兩個步驟。第一步是定義安全性實現(xiàn)，第二步是調(diào)用它們。本節(jié)中定義的 Security 對象用于調(diào)用實際的安全性定義。定義安全性實現(xiàn)是在“組件”部分中完成的，本文后面將詳細介紹。
這是安全對象的一個??例子：
security:
- ApiKeyAuth: []
- OAuth2:
- read
- write
components:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key在上面的例子中，ApiKeyAuth 在 Security 對象下被調(diào)用，但該對象的實際定義應該在components 對象下完成。
本部分展示了 API 公開的各種端點以及相應的 HTTP 方法。每種方法下還詳細介紹了實際的請求-響應周期。請求由 Parameter 對象描述，響應由 Responses 對象描述。
參數(shù)是請求中的可變部分。使用 OAS 3.0 可以指定四種類型的參數(shù)：
響應是請求后返回的對象。每個響應都由其 HTTP 狀態(tài)代碼和返回的數(shù)據(jù)定義。使用的 HTTP 狀態(tài)代碼定義請求是成功還是失敗。要查看 HTTP 狀態(tài)代碼列表，請閱讀此處。
這是一個簡單響應的示例：
responses:
200:
description: Successful Response
content:
text/plain:
schema:
type: string
example: Example string is here隨著您向 API 公開更多資源和操作，合同可能會變得非常長。您的 API 可能會在許多不同的路徑和操作中重復大量現(xiàn)有參數(shù)或響應描述，每次重寫它們都容易導致描述不一致，并且可能非常耗時。
組件對象可以保存 API 設計的一組可重用對象。可重用對象可以是架構(gòu)、響應、參數(shù)、示例等。然后可以在任何路徑項中引用確切的可重用組件。
以下是組件對象的一個??示例：
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標簽是用于對各種操作進行分組的友好類別。這允許 API 的消費者更好地細分和識別他們想要使用 API 做什么。這些標簽也可以由集成或讀取 OAS 的其他第三方工具處理。
使用 tags 對象可以自動將標簽添加到每個路徑操作。通過在 API 定義的根級別中添加可選的 tags 部分，您可以更好地描述每個標簽的含義。
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當然，這只是對與 OpenAPI 設計的 API 相關(guān)的各個部分的一般概述。設計是主觀的，雖然 OAS 為您提供了描述 API 所需的規(guī)則和項目，但如何使用它們有效地傳達 API 的價值才是優(yōu)秀設計的關(guān)鍵。我過去曾介紹過 API 設計的良好實踐，
設計可能是 API 生命周期中最重要的方面之一，因此需要專用工具。Swagger的 OpenAPI 編輯器是開始 API 設計流程的絕佳方式。它簡潔、高效，并配備了許多功能，可幫助您開箱即用地設計 RESTful 接口。
原文鏈接：OpenAPI-Driven API Design
