在开发的过程中,为了方便测试,需要进行使用swagger的页面或者knief4j,然后在页面上进行测试,也可以使用yapi,yapi可以导出word、html等信息,现将swagger的数据变成html、word、markdown。

pom依赖

 </dependencies>
        <dependency>
            <groupId>io.github.swagger2markup</groupId>
            <artifactId>swagger2markup</artifactId>
            <version>1.3.3</version>
        </dependency>
        <dependency>
            <groupId>io.swagger.core.v3</groupId>
            <artifactId>swagger-core</artifactId>
            <version>2.1.10</version>
        </dependency>
        <dependency>
            <groupId>io.swagger.core.v3</groupId>
            <artifactId>swagger-models</artifactId>
            <version>2.1.10</version>
        </dependency>
        <dependency>
            <groupId>org.pegdown</groupId>
            <artifactId>pegdown</artifactId>
            <version>1.6.0</version>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
        </dependency>
    </dependencies>

build依赖:

<build>
    <plugins>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
        </plugin>
        <plugin>
            <groupId>io.github.swagger2markup</groupId>
            <artifactId>swagger2markup-maven-plugin</artifactId>
            <version>1.3.7</version>
            <configuration>
                <swaggerInput>http://localhost:31396/wocloud-dashboard/v2/api-docs</swaggerInput><!---swagger-api-json路径-->
                <outputDir>src/docs/markdown/generated/all</outputDir><!---生成路径-->
                <config>
                    <!--<swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>--><!--生成doc格式-->
                    <swagger2markup.markupLanguage>MARKDOWN</swagger2markup.markupLanguage><!--生成markdown格式-->
                </config>
            </configuration>
        </plugin>

        <plugin>
            <groupId>org.asciidoctor</groupId>
            <artifactId>asciidoctor-maven-plugin</artifactId>
            <version>2.1.0</version>
            <configuration>
                <sourceDirectory>src/docs/asciidoc/generated</sourceDirectory>
                <outputDirectory>src/docs/asciidoc/html</outputDirectory>
                <backend>html</backend>
                <attributes>
                    <!--导航栏在左-->
                    <toc>left</toc>
                    <!--显示层级数-->
                    <toclevels>3</toclevels>
                    <!--自动打数字序号-->
                    <sectnums>true</sectnums>
                </attributes>
            </configuration>
        </plugin>
    </plugins>
</build>

代码生成

    @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://localhost:31396/wocloud-dashboard/v2/api-docs"))
                .withConfig(config)
                .build()
                .toFile(Paths.get("./docs/asciidoc/generated/all"));
    }

在执行插件或者代码之前,先把相应的目录的创建出来,不然会出现异常。

参考文献