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

最新推荐文章于 2024-08-10 07:25:23 发布

原创

最新推荐文章于 2024-08-10 07:25:23 发布 · 1.8k 阅读

0 ·

CC 4.0 BY-SA版权

文章标签：

#swagger #API

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

本示例展示的前提是已经生成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));//设置生成文件的路径
}

/**
 * 生成Markd