Swagger2 导出api文档(AsciiDocs、Markdown)

最新推荐文章于 2025-03-20 13:45:32 发布

熬夜是小狗

最新推荐文章于 2025-03-20 13:45:32 发布

阅读量8k

点赞数

分类专栏： java 文章标签： swagger 导出 Markdown

本文链接：https://blog.csdn.net/Icannotdebug/article/details/83025674

版权

java 专栏收录该内容

31 篇文章

订阅专栏

1.引入pom（用阿里镜像，否则jar下不下来）

严格按照我的版本号，否则jar包版本会出错

<dependencies>
        <dependency>
        <groupId>io.github.swagger2markup</groupId>
        <artifactId>swagger2markup</artifactId>
        <version>1.3.1</version>
    </dependency>
    <dependency>
        <groupId>ch.netzwerg</groupId>
        <artifactId>paleo-core</artifactId>
        <version>0.10.2</version>
    </dependency>
    <dependency>
        <groupId>io.vavr</groupId>
        <artifactId>vavr</artifactId>
        <version>0.9.2</version>
    </dependency>
        <dependency>
            <groupId>junit</groupId>
            <artifactId>junit</artifactId>
            <version>RELEASE</version>
        </dependency>
    </dependencies>

2.编写测试类

package com.jackie.test;

import io.github.swagger2markup.GroupBy;
import io.github.swagger2markup.Language;
import io.github.swagger2markup.Swagger2MarkupConfig;
import io.github.swagger2markup.Swagger2MarkupConverter;
import io.github.swagger2markup.builder.Swagger2MarkupConfigBuilder;
import io.github.swagger2markup.markup.builder.MarkupLanguage;
import org.junit.Test;
import java.net.URL;
import java.nio.file.Paths;

/**
 * @author <a href="mailto:dragonjackielee@163.com">李智龙</a>
 * @since 2018/10/11
 */
public class ExportSwagger {
    /**
     * 生成AsciiDocs格式文档
     * @throws Exception
     */
    @Test
    public void generateAsciiDocs() throws Exception {
        //    输出Ascii格式
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.ASCIIDOC)
                .withOutputLanguage(Language.ZH)
                .withPathsGroupedBy(GroupBy.TAGS)
                .withGeneratedExamples()
                .withoutInlineSchema()
                .build();
        // swagger-ui.html页面中能找到此链接
        Swagger2MarkupConverter.from(new URL("http://localhost:8016/v2/api-docs"))
                .withConfig(config)
                .build()
                .toFolder(Paths.get("./docs/asciidoc/generated"));
    }

    /**
     * 生成Markdown格式文档
     * @throws Exception
     */
    @Test
    public void generateMarkdownDocs() throws Exception {
        //    输出Markdown格式
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.MARKDOWN)
                .withOutputLanguage(Language.ZH)
                .withPathsGroupedBy(GroupBy.TAGS)
                .withGeneratedExamples()
                .withoutInlineSchema()
                .build();

        Swagger2MarkupConverter.from(new URL("http://47.244.30.85:8083/v2/api-docs"))
                .withConfig(config)
                .build()
                .toFolder(Paths.get("/Library/lizhilong/zhanrong/aboutproject"));
    }
//  /**
//   * 生成Confluence格式文档
//   * @throws Exception
//   */
//  @Test
//  public void generateConfluenceDocs() throws Exception {
//      //    输出Confluence使用的格式
//      Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
//              .withMarkupLanguage(MarkupLanguage.CONFLUENCE_MARKUP)
//              .withOutputLanguage(Language.ZH)
//              .withPathsGroupedBy(GroupBy.TAGS)
//              .withGeneratedExamples()
//              .withoutInlineSchema()
//              .build();
//
//      Swagger2MarkupConverter.from(new URL("http://localhost:8016/v2/api-docs"))
//              .withConfig(config)
//              .build()
//              .toFolder(Paths.get("./docs/confluence/generated"));
//  }

    /**
     * 生成AsciiDocs格式文档,并汇总成一个文件
     * @throws Exception
     */
    @Test
    public void generateAsciiDocsToFile() throws Exception {
        //    输出Ascii到单文件
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.ASCIIDOC)
                .withOutputLanguage(Language.ZH)
                .withPathsGroupedBy(GroupBy.TAGS)
                .withGeneratedExamples()
                .withoutInlineSchema()
                .build();

        Swagger2MarkupConverter.from(new URL("http://localhost:8016/v2/api-docs"))
                .withConfig(config)
                .build()
                .toFile(Paths.get("./docs/asciidoc/generated/all"));
    }

    /**
     * 生成Markdown格式文档,并汇总成一个文件
     * @throws Exception
     */
    @Test
    public void generateMarkdownDocsToFile() throws Exception {
        //    输出Markdown到单文件
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.MARKDOWN)
                .withOutputLanguage(Language.ZH)
                .withPathsGroupedBy(GroupBy.TAGS)
                .withGeneratedExamples()
                .withoutInlineSchema()
                .build();

        Swagger2MarkupConverter.from(new URL("http://47.244.30.85:8083/v2/api-docs"))
                .withConfig(config)
                .build()
                .toFile(Paths.get("/Library/lizhilong/zhanrong/aboutproject"));
    }
}