Slate vs Swagger - 哪个更好，哪个有更多选择？

Question

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

Answer 1

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

  

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

〜API Design Tooling From Swagger

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

1. 两者并不相互排斥
2. 理想情况下，应该从Swagger API说明
生成您的平板文档

Swagger的目标是提供一个标准，其他人可以构建广泛的工具（例如：文档，API资源管理器，模拟服务器，代码生成，测试实用程序等）。例如，请参阅：Swagger Tooling

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

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

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

Answer 2

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

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

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

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

Answer 3

关于Slate：
- API文档模板/框架
- 看起来不错 - 易于使用
- 语法突出显示
- 特定语言 - 选项卡
- 页面搜索
- 3柱式可定制布局
- 我们可以创建表格 - 可滚动链接到每个块/方法/标题
- 警报设施[3种类型] - 警告，成功，通知
- http错误代码的表
- Markdown语法
- 我们可以使用Site logo
- Demo

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

Answer 4

我根据python-flask制作了slate-flask（https://github.com/AhnSeongHyun/slate-flask）。

特点：

• 配置文件（config.json）：使用基于JSON格式的config.json为示例代码设置标题，编程语言。还要设置API文档的路径和目录（目录）。

• 支持多API文档：原始Slate支持基于Markdown格式的一个API文档。但是，slate-flask支持使用TOC（index.json）进行有效管理和文档数量的多API文档。

• 支持文档的动态更改：您可以在不重新启动服务器的情况下反映API文档的更改。当网页刷新时，如果存在更改，则slate-flask重新加载API文档。用户只关注编写API文档。