API
如何正确编写 REST API 文档
好的 API 文档需要把机器可读契约、人类解释、可运行示例和明确的错误行为结合起来。 REST API 文档同时面向机器和人。机器可读契约描述 path、method、parameter、schema 与 response；人类文档解释意图、约束、工作流和开发者要做的选择。
2 分钟阅读
OpenAPI
标签文章: OpenAPI
API
OpenAPI 是事实来源，但不是完整的 API 文档
OpenAPI 描述可以生成准确的 reference 结构，但开发者仍需要概念、任务流程、身份认证、示例和错误恢复，这些不是一个 schema 能单独解释的。 OpenAPI 非常擅长描述 operation、parameter、request/response 结构、status code 和可复用 schema。
2 分钟阅读