Swagger集成

Swagger 是一款用於構建、描述、調用和可視化 RESTful API 的開源工具。它可以根據代碼自動生成 API 文檔，方便開發人員進行介面文檔的編寫和測試。本文將從多個方面對 Swagger 集成進行詳細的闡述。

一、Swagger 簡介

Swagger 是由 Tony Tam 在 2011 年創建的一個開源項目。它旨在簡化 RESTful API 的開發和文檔生成，並且可以通過自動生成的 API 文檔來提高溝通效率。Swagger 可以支持多種編程語言和框架。

通常情況下，RESTful API 的開發涉及到以下方面：

• 定義資源
• 定義 HTTP 方法
• 定義認證
• 定義錯誤響應
• 編寫業務邏輯代碼
• 編寫測試代碼
• 編寫文檔

這些工作很繁瑣，而 Swagger 可以根據代碼自動生成 API 文檔，從而省去了很多手動編寫文檔的時間和精力。

二、Swagger 集成

Swagger 的集成非常簡單，只需要在項目中加入 Swagger 的相關依賴即可。

1、Maven 集成

使用 Maven 構建項目時，在 pom.xml 文件的依賴中加入以下內容即可：

  <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger2</artifactId>
      <version>2.9.2</version>
  </dependency>

  <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger-ui</artifactId>
      <version>2.9.2</version>
  </dependency>

同時，在啟動類中加入註解 @EnableSwagger2 即可啟用 Swagger。

  package com.example.demo;

  import org.springframework.boot.SpringApplication;
  import org.springframework.boot.autoconfigure.SpringBootApplication;
  import springfox.documentation.swagger2.annotations.EnableSwagger2;

  @SpringBootApplication
  @EnableSwagger2
  public class DemoApplication {

      public static void main(String[] args) {
          SpringApplication.run(DemoApplication.class, args);
      }

  }

啟動應用，訪問 http://localhost:8080/swagger-ui.html 即可看到 Swagger 自動化生成的 API 文檔。

2、Spring Boot 集成

在 Spring Boot 中集成 Swagger 更加方便，只需要加入以下 Maven 依賴即可：

  <dependency>
      <groupId>springfox.documentation</groupId>
      <artifactId>springfox-swagger2</artifactId>
      <version>2.9.2</version>
  </dependency>

  <dependency>
      <groupId>springfox.documentation</groupId>
      <artifactId>springfox-swagger-ui</artifactId>
      <version>2.9.2</version>
  </dependency>

然後在 Application 啟動類中加入註解 @EnableSwagger2 即可啟用 Swagger。

  package com.example.demo;

  import org.springframework.boot.SpringApplication;
  import org.springframework.boot.autoconfigure.SpringBootApplication;
  import springfox.documentation.swagger2.annotations.EnableSwagger2;

  @SpringBootApplication
  @EnableSwagger2
  public class DemoApplication {

      public static void main(String[] args) {
          SpringApplication.run(DemoApplication.class, args);
      }

  }

啟動應用後，訪問 http://localhost:8080/swagger-ui.html 即可查看生成的 API 文檔。

三、配置與使用

Swagger 集成之後，我們需要對其進行配置和使用。

1、配置

Swagger 配置很靈活，可以進行各種自定義設置。

我們可以通過在配置類中加入 Bean 對象來配置一些 Swagger 的默認信息。

  package com.example.demo.config;

  import org.springframework.context.annotation.Bean;
  import org.springframework.context.annotation.Configuration;
  import springfox.documentation.builders.ApiInfoBuilder;
  import springfox.documentation.builders.PathSelectors;
  import springfox.documentation.builders.RequestHandlerSelectors;
  import springfox.documentation.service.ApiInfo;
  import springfox.documentation.service.Contact;
  import springfox.documentation.spi.DocumentationType;
  import springfox.documentation.spring.web.plugins.Docket;
  import springfox.documentation.swagger2.annotations.EnableSwagger2;

  @Configuration
  @EnableSwagger2
  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("Demo API")
                  .description("Demo API Doc")
                  .version("1.0")
                  .contact(new Contact("Swagger", "https://swagger.io", ""))
                  .build();
      }

  }

在這個配置文件中，我們通過 Docket 類進行了各種設置，包括掃描控制器包、顯示文檔的路徑、設置 API 相關信息等。可以看到其中設置了 API 的標題、描述、版本、聯繫信息等。通過 Bean 註解將這個 Docket 對象放入 Spring 容器中，就能夠自動生效。

2、使用

Swagger 使用非常簡單，只需要在控制器上加入一些註解即可。

首先，我們需要在控制器類上加入 @Api 註解，標識這是一個 API 控制器，同時可以設置一些額外信息。

  package com.example.demo.controller;

  import io.swagger.annotations.Api;
  import io.swagger.annotations.ApiOperation;
  import org.springframework.web.bind.annotation.GetMapping;
  import org.springframework.web.bind.annotation.RequestMapping;
  import org.springframework.web.bind.annotation.RestController;

  @RestController
  @Api(value = "DemoController", tags = {"Demo"})
  @RequestMapping("/demo")
  public class DemoController {

      @ApiOperation(value = "Hello World API", notes = "返回 Hello World")
      @GetMapping("/hello")
      public String hello() {
          return "Hello World!";
      }

  }

在 hello 方法上加入 @ApiOperation 註解，即可設置其請求方法、介面描述、介面參數、返回值等信息。其中 value 表示介面的名稱，notes 表示介面的描述。

這樣，Swagger 就會自動通過掃描控制器類和註解信息來繪製出可視化的 API 文檔。

四、結語

本文對 Swagger 集成進行了詳細的闡述，包括 Swagger 的簡介、集成、配置和使用。Swagger 作為一款非常好用的工具，在 RESTful API 的開發和文檔編寫時有著很大的作用和價值。