石板 vs. Swagger - 哪个更好，哪个选项更多？

Question

石板 vs. Swagger - 哪个更好，哪个选项更多？

documentationswaggerapi-docswagger-editor

36

我需要记录我的API。我必须使用其中之一Slate或者Swagger。我想知道哪一个选项更多、优缺点和哪一个更好。

最初的回答：

如果你想要更多的选项和灵活性，那么选择Slate是更好的选择。但是，Swagger有更广泛的社区支持和更容易上手的界面。

- Sariban D'Cl

4个回答

5

Slate简介:
- API文档模板/框架
- 界面美观
- 易于使用
- 语法高亮
- 支持多种语言，可进行分栏
- 页面搜索功能
- 可自定义三列布局
- 我们可以创建表格
- 每个块/方法/标题都有可滚动的链接
- 警告设施[3种类型] - 警告、成功、通知
- HTTP错误代码表格
- Markdown语法
- 我们可以使用网站标志
- 演示

Swagger简介:
- 它在文档中提供API访问，我们可以检查任何特定请求的响应。
- 它清晰地显示了API响应及其参数和选项的情况。
- 基于YAML格式
- 不适用于超媒体API
- Swagger没有设计工具
- 响应为XML或JSON格式
- Swagger JS--JavaScript库，可通过浏览器或nodejs连接到swagger-enabled APIs
- Swagger Node Express--用于node.js express模块的Swagger模块
- 它具有swagger UI框架
- 演示

- Sariban D'Cl

4

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

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

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

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

- Neoecos

感谢您的回答，@Neoecos。我已经开始使用Swagger进行文档编写了。 - Sariban D'Cl

@SaribanD'Cl 如果这个答案有用，请接受答案并点赞 ✓ - Neoecos

1

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

- ash84

网页内容由stack overflow 提供, 点击上面的

可以查看英文原文，
原文链接

- toast38coza · Accepted Answer

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

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

~ Swagger提供的API设计工具

另一方面，Slate是一种漂亮的主题，用于编写良好的API文档。

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

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

更多关于您的问题：Swagger的一些Slate工具：

这里是一个 Slate主题的Swagger UI链接
这里有一个项目，可以根据你的Swagger定义生成Slate文档

因此，这两者并不是互斥的，但针对您的直接问题：实现Swagger将为您提供更多选项和更大的灵活性（以及生成Slate文档的能力）。