API文檔：OpenAPI, Swagger, Postman

TL;DR

OpenAPI是真理的來源：合同→ SDK →洗滌→測試→門戶。
Swagger UI/Redoc是可讀的展示櫃；Postman-可執行腳本。
Washing linters, breaking-checks,示例和錯誤模式,生成SDK和Mock服務器,我們發布一個帶有轉換和「日落」的dev門戶。

1）目標和原則

合同一（OpenAPI）。其他一切都會產生。
可執行文檔：在Postman/CLI中測試查詢示例。
默認安全性：錯誤模式、限制、身份驗證。
測試和生命周期：「v1」/「v2」，Deprecation/Sunset，changelog。

2） OpenAPI結構（最小骨架）

yaml openapi: 3. 0. 3 info:
title: Payments API version: 1. 2. 0 description: >
Payment transactions: auth/capture/refund/payout. All responses contain trace_id.
servers:
- url: https://api. example. com/v1 tags:
- name: Payments
- name: Payouts components:
securitySchemes:
oauth2:
type: oauth2 flows:
clientCredentials:
tokenUrl: https://idp. example. com/oauth/token scopes:
payments: read: read payments: write: write payments schemas:
Error:
type: object required: [error, error_description, trace_id]
properties:
error: { type: string }
error_description: { type: string }
trace_id: { type: string, format: uuid }
security:
- oauth2: [payments:read]
paths:
/payments/{id}:
get:
summary: Receive payment tags: [Payments]
parameters:
- in: path name: id required: true schema: { type: string, format: uuid }
responses:
'200':
description: Content succeeded:
application/json:
schema: { $ref: '#/components/schemas/Payment' }
'404': { $ref: '#/components/responses/NotFound' }
components:
responses:
NotFound:
description: Content not found:
application/json:
schema: { $ref: '#/components/schemas/Error' }

• 在「組件」中布置schemas/responses/parameters/requestBodies。
• 描述securitySchemes （OAuth2/JWT/HMAC）並在「paths」/「global」級別應用。

3）錯誤標準和元數據

yaml components:
schemas:
ApiError:
type: object required: [error, error_description, trace_id]
properties:
error: { enum: [invalid_request, not_found, rate_limited, internal] }
error_description: { type: string }
trace_id: { type: string, format: uuid }

始終記錄429 （rate limit）、401/403和「X-RateLimit-」、「Retry-After」標題。

4）示例： request/response、curl和SDK

對於每個端點：最小和擴展示例。
從OpenAPI生成curl和嗅探代碼（JS/Python/Go）；不要用手寫字。
應用實際值：UUID、ISO日期、「次要」（cents）總和。

yaml examples:
ok:
value:
id: "pay_123"
amount_minor: 1099 currency: "EUR"
status: "captured"
created_at: "2025-11-03T12:34:56Z"

5）Swagger UI/Redoc-如何發布

1.Swagger UI（互動，試用），

2.Redoc（可讀的長頁）。

包括：黑暗主題，搜索，測試選擇器（「v1」，「v2」），發育橫幅。

將「Try it out」 screw for prod domain,允許在sandbox上。

6）Postman系列： 現場劇本

從OpenAPI自動生成集合,並支持環境變量（'{baseUrl}「,'{{accessToken}」）。
添加pretests（獲取令牌）和後測試（assert狀態/方案）。
按文件夾分解：Auth、Payments、Payouts、Webhooks。
導出關鍵路由的監視器（按計劃）。

js pm. test("status is 200", () => pm. response. code === 200);
pm. test("schema valid", () => tv4. validate(pm. response. json(), pm. collectionVariables. get("schema_payment")));

7）洗滌和三明治

從OpenAPI生成mock服務器（以/'example'/'examples'為例）。
指定摩克限制：等效性，延遲，意外錯誤（對於UAT）。
記錄sandbox vs prod的差異（限制、數據、延遲）。

8）自動發生SDK

從OpenAPI生成官方SDK （TypeScript, Python, Go）。
SDK發行策略=SemVer，映射到API版本。
在README SDK中：身份驗證，轉發，等效性，429/Retry-After處理。

9）Linting，斷裂檢查和CI

Linters： spectral（樣式/反模式）,openapi-diff（斷開檢查）。

CI:

電路驗證器，

linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter linter、

contract tests面對moc服務器,

Swagger/Redoc/集合，

發布到門戶網站（staging→prod），

發布/日落警報。

10） Version, Deprecation, Sunset

URI（'/v1'）和'info中的版本。version`.

過時標誌： 標題「Deprecation： true」, 「Sunset： 」,「Link： 」.

門戶網站上有一個橫幅和計時器，直到關閉為止；v1的Postman Collection已凍結（僅限bagfix）。

11）碼頭的安全性和隱私

不要發布秘密，內部URL，真實PAN/PII。
對於敏感字段-偽裝和示例存根。
Swagger 「Try it out」僅適用於sandbox，帶有等級限制。
清楚地描述OAuth2/OIDC，HMAC（用於webhook）和mTLS（如果需要）。

12）合同樣式海德

復數形式的資源是：「/payments」，「/payouts」。
標識符為「pay_」，「po_」，UUIDv4或ksuid。
日期-UTC ISO-8601；金錢是'amount_minor+currency'。
分區是基於cursor（'？cursor=&limit='）的穩定排序。
異位性是突變的「Idempotency-Key」。
穩定對象「meta」和「links」用於列表。

13）碼頭的「Webhooks」部分

一個單獨的部分，其中包含事件信封，HMAC簽名，時間窗口，轉發和響應代碼。
事件主體的示例和用於本地簽名驗證的Postman集合。
Endpoints replay/DLQ和UAT支票清單。

14）開發門戶： 角色和出版物

章節： 概述,開始,身份驗證,殘局,示例,Webhuki, SDK,限制,Changelog.

角色：Steward API（標準），Domain Owner（內容），Tech Writer（編輯），DevRel（門戶/社區）。
Ficha：搜索方案字段,復制樣本,「收集查詢」→ Postman。

15）支票單

• OpenAPI驗證；linter沒有錯誤。
• 示例包括200/4xx/429/5xx。
• 安全性：描述了auth模式，沒有秘密。
• 由Swagger/Redoc和Postman（prod/sandbox）組成。
• 由SDK生成並發布。
• 更新changelog和測試選擇器。

• Deprecation/Sunset標題包括在內。
• 門戶網站上的橫幅，給合作夥伴的信。
• 傳統版本的調用度量會降至目標級別。

16）反模式

重復真理源（Wiki ≠ OpenAPI）。
在Postman中未啟動的「按眼睛」示例。
沒有單一的錯誤格式。
「query參數」版本而不是URI/域。
Swagger可訪問跨度且無限制。
不一致的分區和身份驗證方案。

17）自動化迷你嗅探

bash openapi2postmanv2 -s openapi. yaml -o postman. json -p

yaml steps:
- run: spectral lint openapi. yaml
- run: openapi-diff --fail-on-breaking main. yaml openapi. yaml
- run: redoc-cli bundle openapi. yaml -o site/redoc. html
- run: swagger-cli bundle openapi. yaml -o site/swagger. json
- run: openapi2postmanv2 -s openapi. yaml -o site/postman. json -p
- run: npm run deploy:portal

18）本地化和可用性

單獨的'info.description_<lang>'或兩個門戶組件（EN/RU）。
詞匯表中的術語（KYC/AML，payout，idempotency）。
對比，鍵盤導航，黑暗主題。

總結

收集文檔流水線：單個OpenAPI合同→ linters和breaking-checks → Swagger/Redoc店面→ Postman系列和moo服務器→ SDK →帶有轉換和Sunset的門戶。定期的示例、統一的錯誤格式和嚴格的身份驗證將把文檔從「PDF上架」轉換為可操作的集成工具,加快合作夥伴速度並降低支持成本。