在接口的开发、测试、维护中，文档是十分必要的。Swagger 是一个规范和完整的框架，用于生成、描述和可视化 RESTful API，而且可与多种编程语言集成。Swagger2markup 则是一个相对比较小众的框架，可以根据 Swagger 规范的 JSON 或者 YAML 文件，生成 AsciiDoc 或者 Markdown 格式的文档。在本文中，将以 Markdown 格式为例，详细讲解如何使用 Swagger2markup 生成 RESTful API 文档。
配置 JAVA 环境与下载 Swagger2markup
在使用 Swagger2markup 前，需要先在机器上安装好 Java 运行环境，打开 Java 官网 进行下载、安装。
之后，在 Swagger2markup 官网 上下载 Swagger2markup 的 Jar 包文件。
生成 Markdown 格式文档的步骤
- 运行 Swagger2markup Convert 工具
Swagger2markup 将根据选定的 Swagger 规范，自动生成由 AsciiDoc 和/或 Markdown 构成的文档。如需生成 Markdown 类型的文档，可在控制台中使用如下命令：
```shell java -jar swagger2markup-1.3.1.jar convert -i [inputSwaggerDoc] -f [outputFile] -m ``` - -i 参数用于指定 Swagger 规范的 JSON 或 YAML 文件的路径，从中生成文档 - -f 参数用于指定输出 Markdown 格式文档的路径 - -m 参数用于生成 Markdown 格式的文档 指定好上述参数后，就可以开始生成 Markdown 格式的文档了。
- 目录规划
Swagger2markup 正是相对较为适合生成大型规范的 API 文档，需要在编写 Swagger 规范的 JSON 或 YAML 文件时遵循一定的规则和约束。
文件约定：为了让 Swagger2markup 能够读取和处理规范文件，所有的约定都应该在文件名上体现。例如规范应该命名为
api.[type].swagger.[yaml|json]，其中[type]是一个 Swagger 规范的特定名称，例如client代表一个客户端 API。锚点标识：在 Markdown 中，锚点标识（anchors）作为跳转链接的地址。锚点标识应该总是有一个前缀：
_与 Swagger 来区别。例如：description: "## _`someObject` object"
Markdown 文件中的 YAML 头部：定义每个文档的元数据。例如：
-- -------------------- ---- ------- --- ------ ---- --- -------------- - --------- - - ------------ - --- - --- --------- ---- ---
- 生成目录和索引
目录和索引的生成十分重要，是让用户和管理者快速浏览和定位到你 API 文档中的主要信息和内容。Markdown 格式的目录和索引应该呈现为：
-- -------------------- ---- ------- ----------- - --- ---- ------------------ -- ---------------------------------- --------------------- -- -------- ------------------------- ----------------- -- ----------------------------- ------------------ -- ----- ------------------------- ------------------- -- ----------------------- --------------- --- ------------------------------------
- 添加路径和操作
Swagger2markup 在处理规范文件时，将所有的操作都转换为所需的 HTML 或者 Markdown 语言结构。
-- -------------------- ---- ------- - -- ------ -- --- ----------- ------- - -- ------ -- --- ------------ ------- -------- -- - ---- ----- ---------- --- ------- ---- --- ----- ----------- - -------- -- ------- -------- ---- ------------ ------- --- ----------- -------- ----- ----------- ------- ---------------- --- --- ----- ---- ------------------ ---- -------
总结
Swagger2markup 是一个十分实用的工具，在开发接口时生成 API 文档会给测试和维护带来巨大的便利。虽然该工具的使用规则和约束相较于其他较为严格，但是掌握好它，能够拓展出更多有用的文档结构和内容。在使用时，需要遵循 YAML 和 AsciiDoc 语言的语法，符合规则的 Swagger 规范将会被自动生成为你所需要的 API 文档。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/6487d16548841e989465d2e9