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 的开发和文档编写时有着很大的作用和价值。