Swagger-UI動態地根據註解生成線上API文件。

參考文章：

mall整合Swagger-UI實現線上API文件（包含詳細的步驟）

mybatis-plus自動生成實體類(包含swagger註解)（因為1中是mybatis的程式碼生成器，另外找了mybatis-plus的）

常用註解

• @Api：用於修飾Controller類，生成Controller相關文件資訊
• @ApiOperation：用於修飾Controller類中的方法，生成介面方法相關文件資訊
• @ApiParam：用於修飾介面中的引數，生成介面引數相關文件資訊
• @ApiModel：用於修飾實體類，生成實體相關文件資訊
• @ApiModelProperty：用於修飾實體類的屬性，當實體類是請求引數或返回結果時，直接生成相關文件資訊

整合步驟

1. 在pom.xml中新增依賴

2. 配置SwaggerConfig檔案

   • 配置Swagger的Docket Bean例項

     .enable(false) 是否啟用swagger

     .apis(RequestHandlerSelectors.**basePackage**("watt.gasleakage.controller"))

     RequestHandlerSelectors 配置要掃描介面的方式

     basePackage 指定要掃描的包

     .apis(RequestHandlerSelectors.**withClassAnnotation**(Api.class))

     withClassAnnotation 掃描類上的註解，引數是一個註解的反射物件，如RestController.class

     .apis(RequestHandlerSelectors.**withClassAnnotation**(ApiOperation.class))

     withMethodAnnotation 掃描方法上的註解，GetMapping.class

     .paths(PathSelectors.any())

     過濾什麼路徑

   • 配置Swagger資訊ApiInfo

   @Configuration  // 配置
   @EnableSwagger2 // 開啟Swagger
   public class SwaggerConfig {
       @Bean
       public Docket docket() {
           return new Docket(DocumentationType.SWAGGER_2)
               .apiInfo(apiInfo())
               .select()
               .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
               .build();
       }
       private ApiInfo apiInfo() {
           Contact contact = new Contact("作者", "連結", "郵箱");
           return new ApiInfoBuilder()
               .title("API文件名")
               .description("API文件描述")
               .version("API文件版本")
               .contact(contact)
               .build();
       }
   }
    
   

3. 修改mybatis-plus程式碼生成器的生成規則

但是我的專案中使用了DTO，在Swagger中顯示請求引數，需要在dto中添加註解。

@ApiModel(value="User物件", description="")

@ApiModelProperty(value = "使用者名稱")

// 全域性配置
GlobalConfig gc = new GlobalConfig(); 
gc.setSwagger2(true); //實體屬性 Swagger2 註解

具體使用

1. 在Controller類上使用

@Api：用於修飾Controller類，生成Controller相關文件資訊

@Api(tags = "AccountController", description = "使用者登入註冊")
@RestController
public class AccountController {}

2. 在Controller類中方法上使用

@ApiOperation：用於修飾Controller類中的方法，生成介面方法相關文件資訊

@ApiParam：用於修飾介面中的引數，生成介面引數相關文件資訊

@ApiOperation("使用者登入")
@PostMapping("login")
public Result login(@Validated @RequestBody @ApiParam("賬號物件") LoginDto loginDto, HttpServletResponse response) {}

3. 在實體類上使用

@ApiModel：用於修飾實體類，生成實體相關文件資訊

@Data
@ApiModel(value="User物件", description="")
public class LoginDto implements Serializable {}

4. 在實體類的屬性上使用

@ApiModelProperty：用於修飾實體類的屬性，當實體類是請求引數或返回結果時，直接生成相關文件資訊

@ApiModelProperty(value = "使用者名稱")
private String userName;