SpringBoot集成Swagger3

Swagger簡介

Swagger是一個規范和完整的框架，用於生成、描述、調用和可視化RESTful風格的Web服務。總體目標是使客戶端和文件系統作為服務器以同樣的速度來更新。文件的方法，參數和模型緊密集成到服務器端的代碼，允許API來始終保持同步。

官網：swagger.io

Swagger解決的痛點

傳統方式提供文檔有以下痛點：

• 接口眾多，實現細節復雜，編寫文檔耗費費力，需要持續維護；
• 接口文檔需要隨時進行同步；
• 接口返回的結果不明確，得構造返回結構體等；
• 不能直接在線測試接口，通常需要額外的工具，比如PostMan等。

當引入Swagger之后，以上痛點迎刃而解，同時還帶來以下優點：

• 及時性 (接口變更后，前后端人員可實時看到最新版本)
• 規范性 (接口具體統一風格，如接口地址，請求方式，參數，響應格式和錯誤信息等)
• 一致性 (接口信息一致，不會因接口文檔版本問題出現分歧)
• 可測性 (可直接基於接口文檔進行測試)

Swagger3的改變

Swagger3.0的改動，官方文檔總結如下幾點：

• 刪除了對springfox-swagger2的依賴；
• 刪除所有@EnableSwagger2...注解；
• 添加了springfox-boot-starter依賴項；
• 移除了guava等第三方依賴；
• 文檔訪問地址改為http://ip:port/project/swagger-ui/index.html。

在SpringBoot項目導入對應的依賴

		<dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>3.0.0</version> </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>3.0.0</version>
        </dependency>

指定配置文件

通常情況下swagger只能在開發環境或測試環境下開啟，生產環境下需要進行關閉的。而swagger的開啟與關閉可在application.yml中進行配置：

# 生產環境需設置為false
springfox:
  documentation:
    swagger-ui:
      enabled: true

配置類

通過@EnableOpenApi注解啟動用Swagger的使用，同時在配置類中對Swagger的通用參數進行配置。

import io.swagger.v3.oas.annotations.Operation;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.HttpMethod;
import springfox.documentation.builders.*;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.schema.ScalarType;
import springfox.documentation.service.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

import java.util.ArrayList;
import java.util.List;

@Configuration
@EnableOpenApi
public class Swagger3Config {

    @Bean
    public Docket createRestApi() {
        //返回文檔摘要信息
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(Operation.class))
                .paths(PathSelectors.any())
                .build()
                .globalRequestParameters(getGlobalRequestParameters())
                .globalResponses(HttpMethod.GET, getGlobalResponseMessage())
                .globalResponses(HttpMethod.POST, getGlobalResponseMessage());
    }

    /**
     * 生成接口信息，包括標題、聯系人等
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Swagger3接口文檔")
                .description("Swagger文檔")
                .contact(new Contact("杜嘟嘟", "https://www.choupangxia.com/", "[e-mail]"))
                .version("1.0")
                .build();
    }

    /**
     * 封裝全局通用參數
     */
    private List<RequestParameter> getGlobalRequestParameters() {
        List<RequestParameter> parameters = new ArrayList<>();
        parameters.add(new RequestParameterBuilder()
                .name("uuid")
                .description("設備uuid")
                .required(true)
                .in(ParameterType.QUERY)
                .query(q -> q.model(m -> m.scalarModel(ScalarType.STRING)))
                .required(false)
                .build());
        return parameters;
    }

    /**
     * 封裝通用響應信息
     */
    private List<Response> getGlobalResponseMessage() {
        List<Response> responseList = new ArrayList<>();
        responseList.add(new ResponseBuilder().code("404").description("未找到資源").build());
        return responseList;
    }

}