SpringBoot整合swagger2生成接口文檔，並且實現導出功能

寫在前言：前陣子工作涉及到與其他公司進行接口對接，要求要swagger文檔，之前沒有用過這個，於是寫了一下，整理出來

1、添加swagger依賴

在項目的pom文件中添加swagger的依賴

<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger2</artifactId>
   <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.8.0</version>
</dependency>

2、編寫swagger的配置類

代碼如下

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //為當前包路徑
                .apis(RequestHandlerSelectors.basePackage("com.anso.data.sync.api.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    //構建 api文檔的詳細信息函數,注意這里的注解引用的是哪個
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //頁面標題
                .title("接口文檔")
                //創建人
                .contact(new Contact("yedan", null, null))
                //版本號
                .version("1.0")
                //描述
                .description("數據對接接口文檔")
                .build();
    }
}

3、swagger在接口上的使用，找到需要生成接口文檔的controller下，對class直接注解@Api("文件說明")，在對應的接口上直接用注解@ApiOperation("系統主動推送數據")標明方法的作用，對於需要傳參的接口可以使用注解@ApiImplicitParam來對參數進行說明，例如：

當有多個參數的時候，可以使用注解@ApiImplicitParams
以上是swagger的使用方式，運行項目可以直接訪問 http://localhost:8028/swagger-ui.html，就可以看到對應的接口文檔

4、可以在頁面上查看swagger文檔后，我們可以繼續配置能夠導出接口文檔，導出html文件的方式，直接在項目的pom文件下添加

<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>

pom文件修改完成后，運行項目，在控制台輸入mvn asciidoctor:process-asciidoc 執行，即可在src下可以看到生成的接口文檔

5、同理，用同樣的方法可以生成MD格式的，修改pom文件

<plugin>
    <groupId>io.github.swagger2markup</groupId>
    <artifactId>swagger2markup-maven-plugin</artifactId>
    <version>1.3.1</version>
    <configuration>
        <!-- api-docs訪問url -->
        <swaggerInput>http://localhost:8028/v2/api-docs</swaggerInput>
        <!-- 生成為單個文檔，輸出路徑 -->
        <outputFile>src/docs/asciidoc/generated/all</outputFile>
        <config>
            <!-- ascii格式文檔 -->
            <swagger2markup.markupLanguage>MARKDOWN</swagger2markup.markupLanguage>
            <swagger2markup.pathsGroupedBy>TAGS</swagger2markup.pathsGroupedBy>
        </config>
    </configuration>
</plugin>

pom文件修改完成后，運行項目，在控制台輸入mvn swagger2markup:convertSwagger2markup 執行，即可在src下可以看到生成的接口文檔
以上就是swagger2生成接口文檔的例子