SpringBoot将Swagger2文档导出为markdown或html

原文参考：http://www.itmuch.com/other/doc-generate/

整合Swagger

1、添加pom.xml依赖

　　　　 <!-- swagger -->
        <!-- 之所以要排除，是因为如果不排除会报NumberFormatException的警告。 -->
        <!-- 参考：https://github.com/springfox/springfox/issues/2265-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
            <exclusions>
                <exclusion>
                    <groupId>io.swagger</groupId>
                    <artifactId>swagger-annotations</artifactId>
                </exclusion>
                <exclusion>
                    <groupId>io.swagger</groupId>
                    <artifactId>swagger-models</artifactId>
                </exclusion>
            </exclusions>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-annotations</artifactId>
            <version>1.5.21</version>
        </dependency>
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-models</artifactId>
            <version>1.5.21</version>
        </dependency>

2、配置Swagger（仅供参考）

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
                // 选择那些路径和api会生成document
                .select()
                // 对所有api进行监控
                .apis(RequestHandlerSelectors.any())
                // 错误路径不监控
                .paths(Predicates.not(PathSelectors.regex("/error.*")))
                .paths(PathSelectors.any()).build();
    }

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("Spring Boot接口文档测试")
                .description("This is a restful api document of SpringBoot Test.")
                .version("1.0")
                .build();
    }
}

3、使用Swagger提供的注解（这里不做描述，网上一搜一大堆）

 

添加 swagger2markup 插件依赖

　　　　　　　　<plugin>
                <groupId>io.github.swagger2markup</groupId>
                <artifactId>swagger2markup-maven-plugin</artifactId>
                <version>1.3.1</version>
                <configuration>
                    <!-- api-docs访问url -->
                    <swaggerInput>http://localhost:8080/v2/api-docs</swaggerInput>
                    <!-- 生成为单个文档，输出路径 -->
                    <outputFile>src/docs/asciidoc/generated/all</outputFile>
                    <config>
                        <!-- ascii格式文档 -->
                        <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
                        <!-- markdown格式文档 -->
                        <!--<swagger2markup.markupLanguage>MARKDOWN</swagger2markup.markupLanguage>-->
                        <!-- 设置输出语言为中文 -->
                        <swagger2markup.outputLanguage>ZH</swagger2markup.outputLanguage>
                        <swagger2markup.pathsGroupedBy>TAGS</swagger2markup.pathsGroupedBy>
                    </config>
                </configuration>
            </plugin>

            <plugin>
                <groupId>org.asciidoctor</groupId>
                <artifactId>asciidoctor-maven-plugin</artifactId>
                <version>1.5.6</version>
                <configuration>
                    <!-- asciidoc文档输入路径 -->
                    <sourceDirectory>src/docs/asciidoc/generated</sourceDirectory>
                    <!-- html文档输出路径 -->
                    <outputDirectory>src/docs/asciidoc/html</outputDirectory>
                    <backend>html</backend>
                    <sourceHighlighter>coderay</sourceHighlighter>
                    <!-- html文档格式参数 -->
                    <attributes>
                        <doctype>book</doctype>
                        <toc>left</toc>
                        <toclevels>3</toclevels>
                        <numbered></numbered>
                        <hardbreaks></hardbreaks>
                        <sectlinks></sectlinks>
                        <sectanchors></sectanchors>
                    </attributes>
                </configuration>
            </plugin>

按照下图的顺序依次执行，即可在配置的路径看到生成的文档