掌握Swagger 2的基础使用

Swagger是一个流行的API文档工具，它可以帮助开发人员设计、构建和维护高质量的API。本文将介绍Swagger 2的基础使用方法，帮助读者快速上手这个强大的工具。

1.引入Swagger 2到项目中

首先，需要将Swagger 2的依赖项添加到项目的构建文件中。如果是使用的Maven，可以在pom.xml文件中加入以下内容：

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

对于Gradle用户，可以在build.gradle文件中添加以下内容： 

implementation 'io.springfox:springfox-swagger2:2.9.2'

2.配置Swagger 2

在项目的配置类中，添加@EnableSwagger2注解以启用Swagger 2。例如：

import org.springframework.context.annotation.Configuration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    // 配置相关Swagger参数
}

3.创建API文档

在控制器类的方法上使用Swagger的注解来描述API。例如：

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

@RestController
@Api(tags = "示例控制器")
public class SampleController {

    @GetMapping("/hello")
    @ApiOperation("你好")
    public String Hello() {
        return "你好Swagger!";
    }
}

 在上述示例中，@Api注解用于为控制器添加一个标签，@ApiOperation注解用于描述具体的API操作。

4.常用Swagger2备注

 4.1 @Api：用于对整个控制器类进行注解，表示该类是 Swagger2 文档的资源。

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

4.2 @ApiOperation：用于对接口方法进行注解，表示该方法是一个操作（或一个 API）。

@ApiOperation("获取所有用户")
@GetMapping("/")
public List<User> getAllUsers() {
    // ...
}

4.3 @ApiParam：用于对参数进行注解，表示该参数在 Swagger2 文档中的说明信息。

@ApiOperation("根据ID获取用户")
@GetMapping("/{id}")
public User getUserById(@ApiParam(value = "用户ID", required = true) @PathVariable Long id) {
    // ...
}

4.4 @ApiModelProperty：用于对实体类属性进行注解，表示该属性在 Swagger2 文档中的说明信息。

public class User {
    @ApiModelProperty("用户ID")
    private Long id;
    
    @ApiModelProperty("用户名")
    private String username;
    
    // ...
}

4.5 @ApiResponse：用于对 API 响应进行注解。

@ApiOperation("创建新用户")
@PostMapping("/")
@ApiResponse(code = 201, message = "用户创建成功")
public void createUser(@RequestBody User user) {
    // ...
}

5.查看生成的API文档

启动应用程序并访问Swagger UI界面（通常是http://localhost:8080/swagger-ui.html）。在这个页面可以看到自动生成的API文档，并且可以在其中测试和调试API。