swagger2markup基于swagger.json生成文档asciidoc、markdown、confluence

最新推荐文章于 2025-05-13 10:02:22 发布

itliwei

最新推荐文章于 2025-05-13 10:02:22 发布

阅读量1.7k

点赞数

分类专栏：基础工具文章标签： swagger API

本文链接：https://blog.csdn.net/itliwei/article/details/84503160

版权

该博客介绍了如何从swagger.json文件通过Swagger2Markup工具，生成包括Asciidoc、Markdown和Confluence格式的API文档。示例中提到了必要的jar包依赖，并展示了代码实现。此外，还提及了生成PDF或HTML文档需要asciidoctor-maven-plugin插件。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

本示例展示的前提是已经生成swagger.json

1、jar包依赖：

<dependency>
  <groupId>io.github.swagger2markup</groupId>
  <artifactId>swagger2markup</artifactId>
  <version>1.1.0</version>
</dependency>

2、代码展示：

/**
 * 生成AsciiDocs格式文档
 * @throws Exception
 */
public static void generateAsciiDocs(String swaggerJsonUrl,String filePath) throws Exception {
    //    输出Ascii格式
    Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
            .withMarkupLanguage(MarkupLanguage.ASCIIDOC)//设置生成格式
            .withOutputLanguage(Language.EN)//设置语言英文，中文可能是乱码
            .withPathsGroupedBy(GroupBy.TAGS)
            .withGeneratedExamples()
            .withoutInlineSchema()
            .build();
    //设置swagger-api的json来源
    Swagger2MarkupConverter.from(new URL(swaggerJsonUrl))
            .withConfig(config)
            .build()
            .toFile(Paths.get(filePath));