後端編寫Swagger介面管理文檔

• 2022 年 8 月 6 日
• 筆記
• javaee

Swagger介面管理文檔

訪問介面文檔的網頁：//localhost:8080/swagger-ui/index.html

導入依賴

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

編寫yaml

SpringBoot 2.6以上版本修改了路徑匹配規則，但是Swagger3還不支援，這裡換回之前的，不然啟動直接報錯

spring:
	mvc:
		pathmatch:
      matching-strategy: ant_path_matcher

創建配置類配置swagger資訊

這個是配置swagger網頁的大文字

@Configuration
public class SwaggerConfiguration {
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfoMyself())
                .select()   //開啟選擇掃描介面功能
                .apis(RequestHandlerSelectors.basePackage("com.example.controller"))    //設置swagger只掃描該包下的介面(還可以設置只掃描每個類，某個方法）
                .build();
    }

    private ApiInfo apiInfoMyself(){
        return new ApiInfoBuilder()
                .contact(new Contact("你的名字", "//www.bilibili.com", "javastudy111*@163.com"))
                .title("圖書館裡系統——在線api介面文檔")
                .description("歡迎各位前端大佬前來訪問介面")
                .version("1.1") //自己隨便定義這個介面第幾版的
                .build();
    }
}

添加具體描述

//為xxxcontroller這個類加註解
@Api(tags = "賬戶驗證介面", description = "包括用戶登錄、註冊、驗證碼請求等操作。")
@RestController
@RequestMapping("/api/auth")
public class AuthApiController {
    
//為某個介面添加註解
@ApiResponses({
        @ApiResponse(code = 200, message = "郵件發送成功"),  
        @ApiResponse(code = 500, message = "郵件發送失敗")   //不同返回狀態碼描述
})
@ApiOperation("請求郵件驗證碼")   //介面描述
@GetMapping("/verify-code")
public RestBean<Void> verifyCode(@ApiParam("郵箱地址") @RequestParam("email") String email,//請求參數的描述
                                @ApiParam("郵箱地址") @RequestParam("email") String email){
    
//讓swagger忽略每個介面
@ApiIgnore     //忽略此請求映射
@PostMapping("/login-success")
public RestBean<Void> loginSuccess(){
    return new RestBean<>(200, "登陸成功");
}
    
//為實體類添加描述（因為有時候會返回一個實體類，所以需要告訴前端人員這個實體類描述的是啥）
@Data
@ApiModel(description = "響應實體封裝類")
@AllArgsConstructor
public class RestBean<T> {

    @ApiModelProperty("狀態碼")
    int code;
    @ApiModelProperty("狀態碼描述")
    String reason;
    @ApiModelProperty("數據實體")
    T data;

    public RestBean(int code, String reason) {
        this.code = code;
        this.reason = reason;
    }
}
    

如果有配置多環境，prod生產環境就沒必要開啟swagger了

springfox:
  documentation:
    enabled: false