寫在前言：前陣子工作涉及到與其他公司進行介面對接，要求要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生成介面文件的例子