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上架"转换为可操作的集成工具,加快合作伙伴速度并降低支持成本。