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