Swagger2 遷移至 SpringDoc openapi

由於springfox swagger在最新的springboot 2.6.x版本中頻頻報錯無法使用，因此計划遷移至springdoc。

這里僅記錄個人使用經驗，更具體的信息見官方文檔。

一、導入依賴

   <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-ui</artifactId>
      <version>1.5.13</version>
   </dependency>

僅需導入這一個依賴即可

二、運行

• springdoc無需注解開啟，正常啟動項目即可

• 默認訪問路徑與swagger2一致：http://server:port/context-path/swagger-ui.html

• 也可在application.yml中自定義訪問路徑，例：

  springdoc:
    swagger-ui:
      path: /swagger-ui
  

三、注解

• swagger2所對應注解，官方文檔中有詳細介紹，這里只寫幾個常用的

• @ApiModel(value = "") -> @Schema(title = "")

  @ApiModelProperty(value = "") -> @Schema(title = "")

  springfox:
  @ApiModel(value= "User")
  public class User {
      @ApiModelProperty(value = "姓名")
      private String name;
  }
  
  springdoc:
  @Schema(title = "User")
  public class User {
      @Schema(title = "姓名")
      private String name;
  }
  

• @Api(tags = "") -> @Tag(name = "")

  @ApiOperation(value = "", tags = {""}) -> @Operation(summary = "", tags = "")

  springfox:
  @Api(tags = "TestController API")
  @RestController
  public class TestController {
      @ApiOperation(value = "根據ID查詢", tags = "TestController API")
      @GetMapping(value = "/{id}")
      public Result selectOne(@PathVariable Long id) {
          ...
      }
  }
  
  springdoc:
  @Tag(name = "TestController API")
  @RestController
  public class TestController {
      @Operation(summary = "根據ID查詢", tags = "TestController API")
      @GetMapping(value = "/{id}")
      public Result selectOne(@PathVariable Long id) {
          ...
      }
  }