SpringBoot: 后台接口文檔 - 基於Swagger3

本文轉載自查看原文 2021-07-29 14:06 673 java/ springboot

前言：什么是Swagger
起步：（只需簡單的3步）
- 加載依賴
- 添加注解@EnableOpenApi
- 啟動SpringBoot，訪問Swagger后台界面
配置：基於Java的配置
注解：Swagger2 和 Swagger3做對比
源碼：https://github.com/Jalon2015/spring-boot-demo/tree/master/demo-swagger3
問題：踩坑記錄（后面再整理）

前言

什么是Swagger：

Swagger 是最流行的 API 開發工具，它遵循 OpenAPI Specification（OpenAPI 規范，也簡稱 OAS）。

它最方便的地方就在於，API文檔可以和服務端保持同步，即服務端更新一個接口，前端的API文檔就可以實時更新，而且可以在線測試。

這樣一來，Swagger就大大降低了前后端的溝通障礙，不用因為一個接口調不通而爭論不休

之前用的看雲文檔，不過這種第三方的都需要手動維護，還是不太方便

起步

加載依賴

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

添加@EnableOpenApi注解

@EnableOpenApi
@SpringBootApplication
public class SwaggerApplication {
    public static void main(String[] args) {
        SpringApplication.run(SwaggerApplication.class, args);
    }
}

啟動項目，訪問"http://localhost:8080/swagger-ui/index.html"

這樣一個簡單的Swagger后台接口文檔就搭建完成了；

下面我們說下配置和注解

配置

可以看到，上面那個界面中，默認顯示了一個basic-error-controller接口分組，但是我們並沒有寫；

通過在項目中查找我們發現，SpringBoot內部確實有這樣一個控制器類，如下所示：

這說明Swagger默認的配置，會自動把@Controller控制器類添加到接口文檔中

下面我們就自己配置一下，如下所示：

import io.swagger.annotations.ApiOperation;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
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.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        // 配置OAS 3.0協議
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .select()
                // 查找有@Tag注解的類，並生成一個對應的分組；類下面的所有http請求方法，都會生成對應的API接口
            	// 通過這個配置，就可以將那些沒有添加@Tag注解的控制器類排除掉
                .apis(RequestHandlerSelectors.withClassAnnotation(Tag.class))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("GPS Doc")
                .description("GPS Doc文檔")
                .termsOfServiceUrl("http://www.javalover.com")
                .contact(new Contact("javalover", "http://www.javalover.cn", "1121263265@qq.com"))
                .version("2.0.0")
                .build();
    }

}

這樣上面那個basic-error-controller就看不見了

注解

我們先看下Swagger2中的注解，如下所示：

@Api：用在控制器類上，表示對類的說明
- tags="說明該類的作用，可以在UI界面上看到的說明信息的一個好用注解"
- value="該參數沒什么意義，在UI界面上也看到，所以不需要配置"
@ApiOperation：用在請求的方法上，說明方法的用途、作用
- value="說明方法的用途、作用"
- notes="方法的備注說明"
@ApiImplicitParams：用在請求的方法上，表示一組參數說明
- @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一個請求參數的各個方面（標注一個指定的參數，詳細概括參數的各個方面，例如：參數名是什么？參數意義，是否必填等）
  - name：屬性值為方法參數名
  - value：參數意義的漢字說明、解釋
  - required：參數是否必須傳
  - paramType：參數放在哪個地方
  - header --> 請求參數的獲取：@RequestHeader
  - query --> 請求參數的獲取：@RequestParam
  - path（用於restful接口）--> 請求參數的獲取：@PathVariable
  - dataType：參數類型，默認String，其它值dataType="Integer"
  - defaultValue：參數的默認值
@ApiResponses：用在請求的方法上，表示一組響應
- @ApiResponse：用在@ApiResponses中，一般用於表達一個錯誤的響應信息
  - code：狀態碼數字，例如400
  - message：信息，例如"請求參數沒填好"
  - response：拋出異常的類
@ApiModel：用於響應類上（POJO實體類），描述一個返回響應數據的信息（描述POJO類請求或響應的實體說明）
（這種一般用在post接口的時候，使用@RequestBody接收JSON格式的數據的場景，請求參數無法使用@ApiImplicitParam注解進行描述的時候）
- @ApiModelProperty：用在POJO屬性上，描述響應類的屬性說明
@ApiIgnore：使用該注解忽略這個某個API或者參數；

上面這些是Swagger2的注解，下面我們看下Swagger3和它的簡單對比

Swagger3注解

接下來我們就用Swagger3的注解來寫一個接口看下效果(其中穿插了Swagger2的注解)

控制器UserController.java

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import io.swagger.v3.oas.annotations.Hidden;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.Parameters;
import io.swagger.v3.oas.annotations.enums.ParameterIn;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.*;
import springfox.documentation.annotations.ApiIgnore;

@Tag(name = "user-controller", description = "用戶接口")
@RestController
public class UserController {

    // 忽略這個api
    @Operation(hidden = true)
    @GetMapping("/hello")
    public String hello(){
        return "hello";
    }

    @Operation(summary = "用戶接口 - 獲取用戶詳情")
    @GetMapping("/user/detail")
    // 這里的@Parameter也可以不加，Swagger會自動識別到這個name參數
    // 但是加@Parameter注解可以增加一些描述等有用的信息
    public User getUser(@Parameter(in = ParameterIn.QUERY, name = "name", description = "用戶名") String name){
        User user = new User();
        user.setUsername(name);
        user.setPassword("123");
        return user;
    }

    @Operation(summary = "用戶接口 - 添加用戶")
    @PostMapping("/user/add")
    // 這里的user會被Swagger自動識別
    public User addUser(@RequestBody User user){
        System.out.println("添加用戶");
        return user;
    }

}

實體類User.java：


import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;

@Schema
@Data
public class User {

    @Schema(name = "username", description = "用戶名", example = "javalover")
    private String username;

    @Schema(name = "password", description = "密碼", example = "123456")
    private String password;

    // 隱藏這個屬性，這樣接口文檔的請求參數中就看不到這個屬性
    @Schema(hidden = true)
    private String email;

}

啟動后運行界面如下：