Slate 和 Swagger 会在什么场景下一起使用？

Question

来自this question我已经看到了

Swagger 和 Slate 有两个不同的用途。 Swagger 是对描述 RESTful API 的标准化方式的尝试。

另一方面，Slate 是编写漂亮 API 文档的漂亮主题。

它进一步指出

两者并不相互排斥 理想情况下，应该根据您的 Swagger API 描述生成您的 slate 文档

我有点困惑。当我已经拥有 Swagger UI like so 时，为什么还需要 slate。

我还需要“记录”什么？我真的在问，因为正如我所说，我对它们的用途有点困惑。

Answer 1

在为新 API 创建文档时，有几件事值得一提。

Swagger 为探索 API 的端点提供了一个非常好的图形界面，但您的文档中还应包含其他内容，包括（但不限于）：

1. 身份验证方法（OAuth/JWT、Basic Auth、Cookie/Session、Apikey/token）
2. 日期输出 + 时区的日期格式
3. API 的过滤/分页/选择/排序设置
4. 存在哪些环境（通常是测试、预生产和生产），包括它们之间的差异。
5. 错误处理，包括错误代码、异常类型和日志记录
6. API 的潜在速率限制
7. 使用 API 的条款和条件