定义
Swagger2Markup是一个将Swagger规范文件转换为标记文档的转换器。它读取Swagger的JSON或YAML描述文件，输出若干AsciiDoc或GitHub Flavored Markdown文档，这些文档可以与人工撰写的说明合并使用[1]。其输入源既可以放在本地，也可以通过HTTP从远程地址获取[3]。
该工具在Swagger体系中处于文档呈现环节。Swagger本身用于描述REST风格的Web服务，通常由框架在运行时或构建时生成接口描述文件；Swagger2Markup则在此基础上把机器可读的描述转成适合人阅读、便于版本管理和静态托管的文本[4]。
原理
转换过程可分为解析与渲染两步。工具内部先使用官方的swagger-parser解析Swagger描述文件，得到内存中的模型对象，再由自研的markup-document-builder按目标标记语言的语法组装输出[1]。同一份模型可以被渲染成不同格式，只需在配置中更换目标标记语言即可[5]。
输出文件通常按内容类型拆分。一次转换往往生成overview、paths、definitions、security等多个文件，分别对应接口概览、路径与操作、数据模型定义和安全方案；调用方也可以选择把结果汇总到单个文件[5]。转换行为通过配置对象控制，例如指定分组方式、输出语言、是否生成示例等[6]。
工具提供扩展点机制以支持定制。扩展需要实现init与apply两个方法，并注册到扩展注册表中；默认实现借助java.util.ServiceLoader自动发现扩展[7]。官方给出的扩展点覆盖概览、路径、安全、定义等文档，以及用于在转换前修改Swagger模型的模型扩展[7]。
发展历程
项目早期以io.github.robwin为组织坐标发布，0.9.2版本的构件即署名Robert Winkler，项目描述为Swagger到标记语言的转换器。Gradle插件的版权声明年份为2015年，作者同样为Robert Winkler[8]。
此后项目迁移到io.github.swagger2markup组织坐标，并陆续发布了命令行工具、Maven插件、Gradle插件等配套组件[2]。1.3.3是使用较广的一个版本，被大量教程和示例采用[6]。最终发布版本为1.3.4，要求至少JDK 8[3]。
项目维护者曾在仓库首页说明无法继续独自维护，并列出待办事项，包括支持Swagger v3、修复缺陷以及把多个仓库合并为多模块仓库[9]。外部项目也记录了该工具停止维护的情况，指出其Maven插件最后一次发布是在2018年，Apache NiFi的Registry组件因此在2022年把REST API文档生成迁移到了swagger-codegen-maven-plugin[10]。
应用
常见用法是生成静态API文档站点。开发者在构建流程中调用该工具，把Swagger描述转成AsciiDoc，再用Asciidoctor工具链渲染为HTML、PDF或EPUB，所得页面可以不依赖运行中的服务，作为静态内容托管[3]。欧洲电信标准协会的仓库中就有脚本，先用该命令行工具把OpenAPI文件转成AsciiDoc，再用asciidoctor-pdf输出PDF。
另一类用法是配合代码优先的开发方式。工具可以与Swagger JAX-RS、Springfox、Spring REST Docs等框架一起使用，把代码中注解生成的接口描述转换成文档，并允许在指定位置插入手写的请求与响应示例[3]。对于把Confluence作为文档管理系统的团队，还可以直接输出Confluence Wiki格式的文件并粘入页面[5]。
在接入方式上，工具既可以作为库由Java代码调用，也提供命令行界面、Maven插件与Gradle插件，并可打包为Docker镜像运行，便于在不修改项目构建配置的前提下转换任意可访问的接口描述地址[1]。
局限
规范版本支持存在上限。工具仅支持Swagger 1.2和2.0规范，未跟进后来的OpenAPI 3.0标准，这使其在新项目中的适用性受限[3]。仓库首页所列的待办事项中，Swagger v3支持位列其中[9]。
维护状态是另一项明显限制。项目已不再受到持续维护，最后的正式版本发布于2018年[10]。与之相关的是依赖获取问题：部分传递依赖在Maven中央仓库中不可得，只能到已转为只读的JCenter仓库获取[10]。
运行环境亦有一定要求。项目至少需要JDK 8；其中命令行工具在JDK 17及以上版本存在已知问题，相关打包方案将其运行时限定为JDK 11。此外，由于输出的是静态文档，接口描述更新后需要重新执行转换才能反映变化[1]。
参见
参考资料
- swagger2markup/swagger2markup repository overview [引用日期2026-10-14]
- swagger2markup [引用日期2026-10-14]
- io.github.swagger2markup:swagger2markup on Maven [引用日期2026-10-14]
- Table of Contents [引用日期2026-10-14]
- Swagger静态文档的生成方法 [引用日期2026-10-14]
- 使用Swagger2Markup实现导出API文档 [引用日期2026-10-14]
- Swagger2Markup Documentation [引用日期2026-10-14]
- swagger2markup-gradle-plugin [引用日期2026-10-14]
- swagger2markup [引用日期2026-10-14]
- NIFI-9630 [引用日期2026-10-14]