SpringBoot整合Swagger框架过程解析

下面为您详细讲解“SpringBoot整合Swagger框架过程解析”的完整攻略。

什么是Swagger?

Swagger是一个开源框架，旨在简化 RESTful Web 服务的开发和文档化，它可以生成能描述API的 JSON、HTML等文档。它包含了一些工具，可以帮助开发人员设计、构建、文档化和使用 RESTful Web 服务。

SpringBoot整合Swagger框架步骤

下面是SpringBoot整合Swagger框架的步骤：

在pom.xml文件中添加Swagger依赖

在pom.xml文件中添加以下依赖：

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

上面的依赖中，springfox-swagger2是Swagger的核心依赖，springfox-swagger-ui是用于显示Swagger UI页面的依赖，这两个依赖是必须添加的。

编写Swagger配置类

创建一个配置类SwaggerConfig.java，代码如下：

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

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot整合Swagger2构建RESTful API")
                .description("更多请关注http://www.example.com/")
                .termsOfServiceUrl("http://www.example.com/")
                .contact("sunf")
                .version("1.0")
                .build();
    }
}

上面的代码中，使用@EnableSwagger2注解启用Swagger2，使用@Configuration注解表示这是一个配置类，使用@Bean注解创建Docket对象，Docket对象是Swagger的核心配置对象，它会定义API文档页面的一些基本信息，比如标题、描述等等，通过apiInfo()方法设置。可以通过select()方法配置API接口扫描的包路径。

编写Controller

创建一个Controller类UserController.java，代码如下：

@RestController
@RequestMapping("/user")
@Api(tags = "用户相关接口")
public class UserController {
    @ApiOperation(value = "获取用户列表", notes = "获取所有用户信息")
    @GetMapping("")
    public List<User> getUserList() {
        // 省略逻辑
    }

    @ApiOperation(value = "获取用户信息", notes = "根据ID获取特定用户信息")
    @GetMapping("/{id}")
    public User getUserById(@PathVariable Long id) {
        // 省略逻辑
    }

    @ApiOperation(value = "新增用户", notes = "新增特定用户")
    @PostMapping("")
    public Boolean addUser(@RequestBody User user) {
        // 省略逻辑
    }

    @ApiOperation(value = "修改用户", notes = "修改特定用户")
    @PutMapping("/{id}")
    public Boolean updateUser(@PathVariable Long id, @RequestBody User user) {
        // 省略逻辑
    }

    @ApiOperation(value = "删除用户", notes = "删除特定用户")
    @DeleteMapping("/{id}")
    public Boolean deleteUser(@PathVariable Long id) {
        // 省略逻辑
    }
}

上面的代码中，使用@Api注解进行API分类，使用@ApiOperation注解定义某个API的基本信息，比如接口名称、接口描述等等。@GetMapping、@PostMapping、@PutMapping、@DeleteMapping注解分别表示HTTP的四个动作（GET、POST、PUT、DELETE）。

启动应用程序

在SpringBoot应用程序的启动类中增加@EnableSwagger2注解，如下所示：

@SpringBootApplication
@EnableSwagger2
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

启动应用程序后，在浏览器中输入URL：http://localhost:8080/swagger-ui.html 即可查看自动生成的API文档页面。

示例演示

下面是两个示例演示：

示例一：获取用户列表

请求URL：

http://localhost:8080/user

返回结果：

[
  {
    "id": 1,
    "name": "张三",
    "age": 20
  },
  {
    "id": 2,
    "name": "李四",
    "age": 25
  }
]

示例二：修改用户

请求URL：

http://localhost:8080/user/1

请求头：

Content-Type: application/json

请求体：

{
  "id": 1,
  "name": "张三",
  "age": 22
}