Spring Boot + Swagger 3 的使用指南

一、概述

Swagger 是一個開源的 API 設計工具，其主要目的是方便開發者設計、構建、文檔化和測試 RESTful API。Swagger 在多個平台上可用，包括 Java、Node.js、JavaScript 等。Swagger 3 是 Swagger 的最新版本，其相比於 Swagger 2 有了很多重大的更新和更新。Spring Boot 是基於 Spring 框架開發的，具有零配置（約定優於配置）的特點，能夠快速地創建獨立的、產品級的 Spring 應用程序。Spring Boot 與 Swagger 3 完美結合，可以為我們提供更加方便、高效的開發體驗，本文將詳細介紹 Spring Boot + Swagger 3 的使用指南。

二、安裝和配置 Swagger 3

在使用 Swagger 3 前，需要在項目的 pom.xml 文件中添加以下依賴，此處我們使用的是最新版本的 swagger 依賴:

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

接下來，我們需要在 Spring Boot 應用程序中配置 Swagger。對於 Spring Boot，我們需要創建一個配置類，並使用 @Configuration 注釋標記它，此外，@EnableSwagger2WebMvc 註解還需要添加，在配置類中，我們還需要配置文檔的基本信息和 API 信息：

@Configuration
@EnableSwagger2WebMvc
public class SwaggerConfig {
  @Bean
  public Docket api() {
    return new Docket(DocumentationType.SWAGGER_2)
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
            .paths(PathSelectors.any())
            .build()
            .apiInfo(apiInfo());
  }

  private ApiInfo apiInfo() {
    return new ApiInfoBuilder()
            .title("Spring Boot Swagger 3 Demo API")
            .description("Spring Boot Swagger 3 Demo API 文檔")
            .version("1.0")
            .build();
  }
}

上述配置代碼用以定義我們的 Swagger 文檔信息。在這裡，我們使用了 Docket API 定義，其中配置了 Spring Boot 應用程序的基類型（.basePackage(“com.example.demo.controller”)），以便找到需要暴露為 RESTful 的控制器。然後，我們還需要創建一個 apiInfo() 方法，來設置文檔的基本信息和 API 信息，可以設置 API 的標題、描述和版本等信息。

三、Swagger 3 註解詳解

Swagger 3 中有很多註解，這些註解可以幫助我們更好地組織、描述和文檔化 RESTful API。下面，我們來了解一下這些註解，並給出使用代碼示例。

1. @Api

該註解用於描述控制器類，可以設置 API 的基本信息，包括其標題、描述、版本等。示例：

@RestController
@Api(tags = "用戶管理")
@RequestMapping("/user")
public class UserController {
  //...
}

2. @ApiOperation

該註解用於描述單個方法，可以設置方法的返回值類型、請求方式、請求地址、方法的作用、參數說明等信息。示例：

@ApiOperation(value = "獲取用戶列表", notes = "所有用戶的列表")
@GetMapping("/list")
public List<User> list() {
  //...
}

3. @ApiParam

該註解用於描述方法中的參數，可以設置參數的名稱、類型、樣例值、是否必填、參數描述等信息。示例：

@ApiImplicitParams({
  @ApiImplicitParam(name = "name", value = "姓名", dataType = "String", paramType = "form", required = true),
  @ApiImplicitParam(name = "age", value = "年齡", dataType = "int", paramType = "form", required = true),
})
@PostMapping("/add")
public void addUser(@RequestParam String name, @RequestParam int age) {
  //...
}

四、Swagger 3 的使用示例

我們以一個簡單的 Spring Boot RESTful API 作為例子，來介紹 Swagger 3 的使用。示例代碼如下：

1. 項目結構

項目的目錄結構示例如下：

  my-project
  ├── src
  │   ├── main
  │   │   ├── java
  │   │   │   └── com.example.demo
  │   │   │       ├── controller // 控制器層
  │   │   │       ├── entity // 實體類
  │   │   │       └── swagger // Swagger 配置
  │   │   └── resources
  │   │       ├── application.properties // 配置文件
  │   │       ├── static
  │   │       └── templates
  │   └── test
  │       └── java
  │           └── com.example.demo
  └── pom.xml // 項目依賴

2. 引入 Swagger 3 依賴

在 pom.xml 文件中，我們需要添加如下依賴：

<dependencies>
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
  </dependency>
  <dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
  </dependency>
</dependencies>

3. 配置 Swagger 3

創建 Swagger 配置類 SwaggerConfig.java，如下：

@Configuration
@EnableSwagger2WebMvc
public class SwaggerConfig {
  @Bean
  public Docket api() {
    return new Docket(DocumentationType.SWAGGER_2)
      .select()
      .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
      .paths(PathSelectors.any())
      .build()
      .apiInfo(apiInfo());
  }

  private ApiInfo apiInfo() {
    return new ApiInfoBuilder()
      .title("Spring Boot Swagger 3 Demo API")
      .description("Spring Boot Swagger 3 Demo API 文檔")
      .version("1.0")
      .build();
  }
}

4. 編寫控制器

新建 UserController.java，如下：

@RestController
@RequestMapping("/user")
@Api(tags = "用戶管理")
public class UserController {
  @ApiOperation(value = "獲取用戶列表", notes = "所有用戶的列表")
  @GetMapping("/list")
  public List<User> list() {
    //...
  }

  @ApiOperation(value = "添加用戶", notes = "根據 User 對象添加用戶")
  @ApiImplicitParam(name = "user", value = "用戶信息", dataType = "User", paramType = "body")
  @PostMapping("/add")
  public void addUser(@RequestBody User user) {
    //...
  }

  @ApiOperation(value = "更新用戶", notes = "根據 User 對象更新用戶")
  @ApiImplicitParam(name = "user", value = "用戶信息", dataType = "User", paramType = "body")
  @PutMapping("/update")
  public void updateUser(@RequestBody User user) {
    //...
  }

  @ApiOperation(value = "刪除用戶", notes = "根據 id 刪除用戶")
  @ApiImplicitParam(name = "id", value = "用戶 ID", dataType = "Long", paramType = "path")
  @DeleteMapping("/{id}")
  public void deleteUser(@PathVariable Long id) {
    //...
  }
}

5. 編寫實體類

新建 User.java，如下：

@Data
public class User {
  private Long id;
  private String name;
  private Integer age;
}

6. 運行應用程序

在項目根目錄下運行 mvn spring-boot:run 啟動應用程序，然後瀏覽器訪問 http://localhost:8080/swagger-ui/ 即可查看介面文檔。

總結

本文主要介紹了 Spring Boot 和 Swagger 3 的集成使用，其中包括了 Swagger 3 的註解詳解。通過本文的介紹，相信您能夠輕鬆上手並熟練使用 Swagger 3，為我們的 RESTful API 開發帶來便利，提高了開發效率。