Spring Boot + Swagger2 自動生成api接口文檔

一、什麼是Swagger

        由於Spring Boot能夠快速開發、便捷部署等特性，相信有很大一部分Spring Boot的用戶會用來構建RESTful API。由於存在多終端的情況（移動端，web前端，小程序等），所以我們會抽象出RESTful API並共用一些底層業務代碼。 

       由於接口衆多，並且細節複雜，所以催生了一些api框架，Swagger就憑藉其使用簡單、實時更新等特點脫穎而出。Swagger可以輕鬆的整合到Spring Boot中，並與Spring MVC程序配合組織出強大RESTful API文檔。它既可以減少我們創建文檔的工作量，同時說明內容又整合入實現代碼中，讓維護文檔和修改代碼整合爲一體，可以讓我們在修改代碼邏輯的同時方便的修改文檔說明。另外Swagger2也提供了強大的頁面測試功能來調試每個RESTful API。

使用SwaggerHub，您可以：

• 以OpenAPI格式定義您的API。

• 將所有API定義託管在一個地方。

• 將常見的API組件（例如數據模型和響應）存儲在域中，並從API定義中引用它們。

• 與您的團隊就API定義進行協作。

• 生成服務器和客戶端代碼，並將其推送到GitHub，GitLab，Bitbucket或Azure DevOps Services。

• 公開和私下共享您的API。

• 迭代API設計並管理多個API 版本。

二、在SpringBoot中使用Swagger

2.1 在pom中添加swagger的依賴

要使用swagge，我們首先需要在項目的pom中添加swagger依賴（這裏使用的是maven構建，如果是gradle請在build.gradle中添加）。我們需要添加的依賴主要有兩個，分別是swagger和swagger-ui，如果要使用其他功能(如接口文檔導出)還需要引入對應的包。

<!--swagger API獲取-->
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger2</artifactId>
	<version>2.9.2</version>
</dependency>
<!--swagger-ui API獲取-->
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger-ui</artifactId>
	<version>2.9.2</version>
</dependency>

2.2 添加swagger配置類

創建SwaggerConfig.java類

package com.oycbest.springbootswagger.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @Description: swagger 配置類
 * @Author oyc
 * @Date 2020/5/5 3:47 下午
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    /**
     * 創建API
     */
    @Bean
    public Docket createRestApi() {
        // 指定掃描包路徑
        return new Docket(DocumentationType.SWAGGER_2) // 指定生成的文檔的類型是Swagger2
//                .pathMapping("/swagger")
                // 用來創建該API的基本信息，展示在文檔的頁面中（自定義展示的信息）
                .apiInfo(apiInfo()) // 配置文檔頁面的基本信息內容
                // 設置哪些接口暴露給Swagger展示
                .select()
                // 掃描所有有註解的api，用這種方式更靈活
                //.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .apis(RequestHandlerSelectors.basePackage("com.oycbest.springbootswagger.controller"))
                // 掃描所有 .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any()).build();
    }

    /**
     * 添加摘要信息
     */
    private ApiInfo apiInfo() {
        // 用ApiInfoBuilder進行定製
        return new ApiInfoBuilder()
                // 設置標題
                .title("描述：Spring Boot中使用Swagger2構建RESTful APIs")
                // 描述
                .description("swagger 測試demo")
                // 作者信息
                .contact("oyc")
                .termsOfServiceUrl("http://www.oycyqr.xyz")
                // 版本
                .version("版本號:" + "1.0.1")
                .build();
    }
}

• @Configuration 配置類，啓動時加載此類
• @EnabledSwagger2 標識項目啓動 SwaggerApi 文檔
• ApiInfo 這個類時Swagger 頁面展示的一些基礎信息
• RequestHandlerSelectors.basePackage("com.oycbest.springbootswagger.controller“) 這裏的com.oycbest.springbootswagger.controller是掃描包的路徑

2.3 在controller中添加swagger接口註解

package com.oycbest.springbootswagger.controller;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * @Description: 測試swagger controller
 * @Author oyc
 * @Date 2020/5/5 3:43 下午
 */
@RestController
@Api(tags = "SwaggerController", description = "SwaggerController | 測試swagger")
@RequestMapping("api")
public class SwaggerController {


    @GetMapping("hello")
    @ApiOperation(value="hello 方法", notes="hello Swagger測試方法--hello")
    public String hello(){
        return "hello";
    }

    @GetMapping("test1")
    @ApiOperation(value="test1 方法", notes="hello Swagger測試方法--test1")
    public String test1(){
        return "test1";
    }

    @GetMapping("test2")
    @ApiOperation(value="test2 方法", notes="hello Swagger測試方法-test2")
    public String test2(){
        return "test2";
    }
}

• @Api 修飾整個類，描述Controller的作用。
• @ApiOperation 修飾一個類的一個方法，或者說一個接口 ，可以描述這個方法的功能和注意事項。若不使用則用函數名作爲方法功能。

       參數：value="說明方法的用途、作用"

                notes="方法的備註說明"

• @apiResponses：用在請求的方法上，表示一組響應
• @ApiResponse：用在@ApiResponses中，一般用於表達一個錯誤的響應信息

        code：數字，例如400
        message：信息，例如"請求參數沒填好"
        response：拋出異常的類

• @ApiImplicitParams 修飾方法，可以描述這個方法的參數的作用。若不使用則用參數名作爲參數的作用。
• @ApiImplicitParam：用在@ApiImplicitParams註解中，指定一個請求參數的各個方面
          name：參數名
          value：參數的漢字說明、解釋
          required：參數是否必須傳
          paramType：參數放在哪個地方
              · header --> 請求參數的獲取：@RequestHeader
              · query --> 請求參數的獲取：@RequestParam
              · path（用於restful接口）--> 請求參數的獲取：@PathVariable
              · body（不常用）
              · form（不常用）    
          dataType：參數類型，默認String，其它值dataType="Integer"       
          defaultValue：參數的默認值
• @ApiModel 修飾實體類，可以描述這個類的功能。
• @ApiModelProperty 修飾實體類的屬性，可以描述這個屬性的作用。
• @ApiIgnore修飾參數、方法和類，可以在自動生成文檔時對修飾的對象進行忽略。
• @ApiError ：發生錯誤返回的信息 

2.4 查看&測試接口

如果沒有引入安全框架或設置路徑攔截機制，可以直接訪問 http://127.0.0.1:8080/[項目名稱]/swagger-ui.html查看接口。

接口列表：

測試接口：

源碼地址：https://github.com/oycyqr/springboot-learning-demo/tree/master/springboot-swagger