4 回答
Swagger 和 Slate 有两个不同的用途。Swagger 是对描述 RESTful API 的标准化方式的尝试（例如，类似于ApiBlueprint）
Swagger 是一种基于 JSON 的 API 定义格式，允许描述 REST API。
另一方面，Slate 是编写漂亮 API 文档的漂亮主题。
- 两者并不相互排斥
- 理想情况下，应该从您的 Swagger API 描述中生成您的 slate 文档
Swagger 的目标是提供一个标准，其他人可以在此基础上构建广泛的工具（例如：文档、API 浏览器、模拟服务器、代码生成、测试实用程序等）。参见，例如：Swagger Tooling
更多问题：一些用于招摇的 Slate 工具：
所以这两者不是相互排斥的，而是你的直接问题：实施 Swagger 会给你更多的选择和更大的灵活性（以及生成 Slate 文档的能力）。
在我看来，这些工具的用途非常不同。Swagger 是一种描述语言，而 slate 仅用于文档。
我使用 swagger 创建了一个描述，从中我可以为我的 API 自动生成不同的客户端，甚至自动生成文档。
您还可以从 swagger 规范创建 Markdown，并在 Slate 中使用这些降价。[1]
关于 Slate：
- API 文档模板/框架
- 看起来不错
- 易于使用
- 语法突出显示
- 语言特定 - 选项卡式
- 页面搜索
- 3 列可定制布局
- 我们可以创建表格
- 到每个块/方法/标题的可滚动链接
- Alert Facility [3 种类型] - 警告、成功、通知
- http 错误代码表
- Markdown 语法
- 我们可以使用站点徽标
- 演示
关于 Swagger：
- 它为我们提供了文档本身内部的 API 访问权限，我们可以在其中检查任何特定请求的响应。
- 它提供了 API 响应及其参数和选项的清晰画面。
- 基于 YAML 的格式
- 不适合超媒体 API
- 没有 Swagger 的设计工具
- 响应采用 XML 或 JSON
- Swagger JS - 通过浏览器或 nodejs 连接到启用 Swagger 的 API 的 JavaScript 库
- Swagger Node Express - Swagger node.js express 模块的模块
- 它有 swagger UI 框架
- 演示
我基于 python-flask制作了 slate-flask（https://github.com/AhnSeongHyun/slate-flask ）。
特征：
配置文件(config.json) : 使用基于 JSON 格式的 config.json 为示例代码设置标题、编程语言。还要设置 API 文档和 TOC（目录）的路径。
支持多 API 文档：原始 Slate 支持一个基于 Markdown 格式的 API 文档。但 slate-flask 支持多 API 文档，可使用 TOC(index.json) 进行高效管理和文档数量。
支持文档的动态变化：无需重启服务器即可反映API文档的变化。当网页刷新时，如果存在更改，slate-flask 会重新加载 API 文档。用户只专注于编写 API 文档。