To-Do Calendar - Day22 用 Swagger 產生 API 文件

2022/06/13
2-minute read
SideProject

這篇要來介紹自動產生 API 文件的好工具—Swagger！

什麼是 Swagger？

Swagger 本質上是一種接口描述語言，用於描述使用 JSON 表示的 RESTful API 。Swagger 與一組開源軟件工具一起使用，以設計，構建，記錄和使用 RESTful Web 服務。簡單來說在開發 API 時，可以使用 Swagger 工具偵測程式碼自動生成 Open API 線上文件。

通常工程師都對寫文件退避三舍，因為維護費時，尤其專案需求隔三岔五改來改去，讓工程師覺得不如把時間拿去趕專案進度(´,_ゝ`)。關於專案的文件，根據經驗運氣好的可能會有線上文件，像是 Google Sheets、Notion，或離線文件 Word、PDF，比較慘的是沒有文件，API 如天女散花散落在 Jira 的各處 Issue 留言中，或是 PM 直接丟整包程式碼叫你自己去找吧…~~(ONE PIECE 來著？)~~

拉回正題，我覺得 Swagger 最棒的一點就是 API 的程式碼與 API 文件會同步更新！不需要額外再修改文件，而且 API 是視覺化的方式列表呈現、排版美觀，也可以直接給前端當做測試 API 的介面，大幅減少溝通及維護文件的成本！實在是後端開發、前端串接的必備工具～～

Swagger 目前有 2.x 和 3.x 兩個主流版本，配置略有不同，以下是以 Swagger 3.x 為例：

匯入 Swagger

在 pom.xml 中添加 Swagger3 的配置

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

添加設定

在application.properties 添加 Swagger 功能開關的設定，通常 Swagger 只會在開發環境或測試環境下開啟
```
# 生產環境需設定為false
springfox.documentation.swagger-ui.enabled=true
```

建立 SwaggerConfig 檔案

使用 @Configuration 註解讓 Spring 載入此設定檔，透過 @EnableOpenApi 註解來啟動 Swagger

可以在 apiInfo 方法加入 API 的基本資訊，包括標題、聯絡人

  @Configuration
  @EnableOpenApi
  public class SwaggerConfig {
      @Bean
      public Docket createRestApi() {
          return new Docket(DocumentationType.OAS_30)
                  .select()
                  .apis(RequestHandlerSelectors.basePackage("com.fiber.todocalendar.controller")) //設定掃描目標
                  .paths(PathSelectors.any()) //設定過濾路徑
                  .build()
                  .apiInfo(apiInfo());
      }

      private ApiInfo apiInfo() {
          return new ApiInfoBuilder()
                  .title("To-Do Calendar")
                  .description("Side project - To-Do Calendar API")
                  .version("1.0.0")
                  .contact(new Contact("Fiber Lin", "https://fiberlin1121.github.io/",
                          "fiber410139@gmail.com"))
                  .build();
      }
  }

在完成了上述配置後，其實已經可以生產文檔內容

添加 API 描述

在 Controller 層加入 Swagger

Swagger 使用的註解及說明：

@Api：將一個 class 標記為 Swagger 資源，一般放在 Controller 上面
- tags：說明 class 的內容
@ApiOperation：用在請求的方法上，說明方法的用途
- value：說明方法的用途
- notes：方法的備註說明
@ApiImplicitParams：用在請求的方法上，表示參數說明
- @ApiImplicitParam：用在 @ApiImplicitParams 註解中，指定一個請求參數的各個方面
  - name：參數名稱
  - value：參數的說明
  - required：參數是否必須傳
  - paramType：參數放在哪個地方
    - header –> 請求引數的獲取：@RequestHeader
    - query –> 請求引數的獲取：@RequestParam
    - path –> 請求引數的獲取：@PathVariable
    - body（不常用）
    - form（不常用）
  - dataType：參數型別，預設 String
  - defaultValue：參數的預設值
@ApiResponses：用在請求的方法上，表示一個 Response
- @ApiResponse：用在 @ApiResponses 中，一般用於表達一個錯誤的 Response 資訊 code：數字，例如400 message：資訊，例如請求參數有誤

實體類相關註解

@ApiModel：一般放在實體類上面
- value：指定別名，不指定時默認為類名
- description：詳細說明
@ApiModelProperty：一般放在實體類的屬性上
- value 描述說明
- example：示範資料
- required：參數是否必須傳
- hidden：是否隱藏該字段，使其不會在 API 文檔中顯示

訪問 Swagger 頁面

運行 SpringBoot，接著在瀏覽器輸入：http://localhost:8080/swagger-ui/
點 Try it out 按鈕，填入參數後進行 API 測試

匯出離線文件

某些情境我們可能要把 API 文件匯出留存或交給其他廠商，此時我們就需要 knife4j 來實現離線文件的匯出

匯入 knife4j

在 pom.xml 中添加 knife4j 的配置

<dependency>
  <groupId>com.github.xiaoymin</groupId>
  <artifactId>knife4j-spring-boot-starter</artifactId>
  <version>3.0.2</version>
</dependency>

啟動 knife4j

在 SwaggerConfig 檔案上面添加 @EnableKnife4j 註解，即可開啟 knife4j 的功能

@Configuration
@EnableKnife4j
@EnableOpenApi
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30)
                .select()
                ...
    }