Slate vs Swagger - 哪个更好，哪个有更多选择？ [关闭]

Question

我必须记录我的 API。我必须使用其中任何一个Slate 或Swagger。我想知道哪个有更多的选择，利弊，哪个更好。

Answer 1

关于 Slate：
- API 文档模板/框架
- 看起来不错
- 易于使用
- 语法高亮
- 特定语言 - 选项卡式
- 页面搜索
- 3 列可自定义布局
- 我们可以创建表
- 每个块/方法/标题的可滚动链接
- 警报设施 [3 种类型] – 警告、成功、通知
- http 错误代码表
- 降价语法
- 我们可以使用网站标志
- Demo

关于 Swagger：
- 它为我们提供了文档本身内部的 API 访问权限，我们可以在其中检查任何特定请求的响应。
- 它提供了 API 响应及其参数和选项的清晰图片。
- 基于 YAML 的格式
- 不适合超媒体 API
- Swagger 没有设计工具
- 响应采用 XML 或 JSON
- Swagger JS -- JavaScript 库，用于通过浏览器或 nodejs 连接到启用 swagger 的 API
- Swagger Node Express -- node.js express 模块的 Swagger 模块
- 它有招摇的 UI 框架
- Demo

Answer 2

Swagger 和 Slate 有两个不同的用途。 Swagger 是一种描述 RESTful API 的标准化方式的尝试（例如，类似于 ApiBlueprint）

Swagger 是一种基于 JSON 的 API 定义格式，允许描述 REST API。

~API Design Tooling From Swagger

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

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

Swagger 的目标是提供一个标准，其他人可以在此基础上构建广泛的工具（例如：文档、API 浏览器、模拟服务器、代码生成、测试实用程序等）。参见，例如：Swagger Tooling

更多问题：一些用于招摇的 Slate 工具：

• 这是link to a Slate themed swagger UI
• 这是一个generates Slate docs based on your Swagger definition的项目

所以这两者不是相互排斥的，而是您的直接问题：实施 Swagger 将为您提供更多选择和更大的灵活性（以及生成 Slate 文档的能力）。

Answer 3

我基于 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 文档。

Answer 4

在我看来，这些工具的用途非常不同。 Swagger 是一种描述语言，而 slate 仅用于文档。

我使用 swagger 创建了一个描述，从中我可以为我的 API 自动生成不同的客户端，甚至自动生成文档。

您还可以根据 swagger 规范创建 Markdown，并在 Slate 中使用这些降价。 [1]

[1]https://github.com/RobWin/swagger2markup