Swagger2Markup 教程

1. 项目介绍

Swagger2Markup 是一个开源工具，用于将 Swagger 规范转换成易于阅读的 AsciiDoc 或 Markdown 格式文档。这使得开发者可以轻松地生成与 API 同步的最新 RESTful API 文档。它被广泛应用于企业级项目，如 Deutsche Telekom AG 和 Restlet，以及 AppDirect 等云服务销售平台。

2. 项目快速启动

安装 Swagger2Markup Maven 插件

在你的 pom.xml 文件中添加以下依赖：

<dependency>
    <groupId>io.github.swagger2markup</groupId>
    <artifactId>swagger2markup-maven-plugin</artifactId>
    <version>latest_version</version> <!-- 替换为最新版本号 -->
    <executions>
        <execution>
            <id>generate-markdown</id>
            <phase>generate-resources</phase>
            <goals>
                <goal>convertSwagger2Markdown</goal>
            </goals>
        </execution>
    </executions>
</dependency>

配置 Swagger2Markup

在 Maven 的 pom.xml 中配置插件参数，指定 Swagger JSON 输入文件和输出目录：

<configuration>
    <inputFile>${project.basedir}/src/main/resources/swagger.yaml</inputFile>
    <outputDir>${project.build.directory}/docs/</outputDir>
    <config>
        <documentTitle>My API Documentation</documentTitle>
        <swagger2MarkupConfig>
            <infoSectionTitle>API Info</infoSectionTitle>
            ...
        </swagger2MarkupConfig>
    </config>
</configuration>

执行生成命令

在命令行中运行 Maven 构建以生成文档：

mvn clean generate-sources

完成后，你会在指定的输出目录下找到 Markdown 格式的 API 文档。

3. 应用案例和最佳实践

• Deutsche Telekom AG 使用 Swagger2Markup 来为他们的 API 提供清晰的 HTML 文档。
• Restlet 在其 API 平台中集成 Swagger2Markup，提供吸引人的 HTML 文档。
• QAware GmbH 通过 Swagger2Markup 创建清晰的 API 文档来支持开发流程。
• AppDirect 利用 Swagger2Markup 动态更新云服务的 API 文档。

最佳实践包括：

• 保持 Swagger 规范的同步，确保文档和实际 API 一致。
• 使用版本控制管理文档，便于追踪变更历史。
• 将文档作为持续集成的一部分自动构建。

4. 典型生态项目

• swagger2markup-cli：Swagger2Markup 的命令行接口（CLI）工具。
• swagger2markup-gradle-plugin：Gradle 插件，同样用于转换 Swagger 到 Markdown。
• spring-swagger2markup-demo：Spring Boot、Springfox 和 spring-restdocs 结合 Swagger2Markup 的示例项目。

以上就是 Swagger2Markup 的基本使用方法和相关案例，开始你的 API 文档之旅吧！