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>

按照下圖的順序依次執行，即可在配置的路徑看到生成的文檔