SpringBoot內建Swgger2

Swagger 簡介

​​Swagger​​ 是一個規範且完整的架構，用于生成、描述、調用和可視化 RESTful 風格的 Web 服務。（Swagger的作用是定義了一個文檔的規範。）

開源的部分包括：

• OpenAPI Specification：API規範，規定了如何描述一個系統的API。
• Swagger Codegen：用于通過API規範生成服務端和用戶端代碼。
• Swagger Editor：用來編寫API規範。
• Swagger UI：用于展示API規範。

非開源的部分包括：

• Swagger Hub：雲服務，相當于Editor + Codegen + UI。
• Swagger Inspector：手動測試API的工具。
• SoapUI Pro：功能測試和安全測試的自動化工具。
• LoadUI Pro：壓力測試和性能測試的自動化工具。

SpringFox

​​SpringFox​​ 是一個開源的API Doc的架構，可以将我們的Controller中的方法以文檔的形式展現。

SpringFox 優勢是：

1. 根據代碼自動生成API文檔，減輕文檔維護工作量。
2. 通過生成文檔的web頁面可以，我們可以直接發起請求，對接口進行測試。

SpringFox 頁面布局

整體布局

接口請求布局

接口響應布局

內建Swagger

引入jar包

<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.9.2</version>
</dependency>      

如果是Spring5可以直接使用3.0:

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

配置Swagger界面

更多配置可以參考​​SpringFox​​。Swagger執行個體Bean是Docket，是以必須通過配置Docket執行個體來配置Swaggger，如果需要配置不同的組，那麼隻需要執行個體化多個Docket就行。

package com.xiaolyuh.config;

import org.springframework.beans.factory.annotation.Value;
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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    //api接口包掃描路徑
    public static final String SWAGGER_SCAN_BASE_PACKAGE = "com.xiaolyuh.controller";
    private static final String VERSION = "1.0.0";

    @Value("${swagger.enable:false}")
    private boolean swaggerEnable;

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                // 分組資訊
                .groupName("預設分組")
                .enable(swaggerEnable)
                .select()
                .apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_BASE_PACKAGE))
                // 可以根據url路徑設定哪些請求加入文檔，這裡可以配置不需要顯示的文檔
                .paths(PathSelectors.any())
                //paths： 這裡是控制哪些路徑的api會被顯示出來，比如下方的參數就是除了/user以外的其它路徑都會生成api文檔
                // .paths((String a) ->
                //       !a.equals("/user"))
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //設定文檔的标題
                .title("使用者資訊文檔")
                // 設定文檔的描述
                .description("文檔描述資訊或者特殊說明資訊")
                // 設定文檔的版本資訊-> 1.0.0 Version information
                .version(VERSION)
                // 設定文檔的License資訊->1.3 License information
                .termsOfServiceUrl("http://www.baidu.com")
                // 設定聯系人
                .contact(new Contact("汪雨浩", "http://www.baidu.com", "[email protected]"))
                .build();
    }
}      

接口定義

Controller

@Api(tags = "使用者資訊查詢", hidden = false)
@RestController
public class PersonController {

    @PostMapping("save")
    @ApiOperation(value = "儲存使用者資訊", httpMethod = "POST")
    public Result<PersonResponse> save(@RequestBody PersonRequest person) {
        person.setId(12L);
        PersonResponse personResponse = new PersonResponse();
        BeanUtils.copyProperties(person, personResponse);
        return Result.success(personResponse);
    }

    @PostMapping("update")
    @ApiOperation(value = "更新使用者資訊", httpMethod = "POST")
    public Result<PersonResponse> update(@RequestBody PersonRequest person) {
        person.setId(12L);
        PersonResponse personResponse = new PersonResponse();
        BeanUtils.copyProperties(person, personResponse);
        return Result.success(personResponse);
    }
}      

VO

@Data
@ApiModel("儲存使用者資訊接口請求參數")
public class PersonRequest {
    @ApiModelProperty(value = "ID",example = "13",  hidden = true)
    private Long id;

    @ApiModelProperty(value = "使用者名", example = "使用者名", allowEmptyValue = true, required = true)
    private String name;

    @ApiModelProperty(value = "年齡", example = "29", allowEmptyValue = false, required = true)
    private Integer age;

    @ApiModelProperty(value = "位址", example = "地球村", allowEmptyValue = false, required = true)
    private String address;
}      

檢視文檔

啟動項目打開​​http://localhost:8080/swagger-ui.html#​​。

Swgger常用注解

注解	說明
@Api(tags = “使用者資訊查詢”, hidden = false)	作用在Controller上，表示是有個子產品
@ApiOperation(value = “儲存使用者資訊”, httpMethod = “POST”)	作用在Controller的方法上，表示一個接口
@ApiModel(“儲存使用者資訊接口請求參數”)	作用在request、response、VO、BO等實體類上，表示定一個模型
@ApiModelProperty(value = “使用者名”, example = “使用者名”, allowEmptyValue = true, required = true)	作用在VO、BO的屬性上，表示一個屬性說明。

源碼位址