SpringBoot+Swagger2常用注解-猿码集

1. Introduction

SpringBoot是一个开源框架，用于更快速、更简便地构建基于Spring的应用程序。Swagger2是一个用于生成、描述、调用和可视化RESTful风格的Web服务的工具。结合使用SpringBoot和Swagger2可以使接口文档的编写更加简便、可读性更好。本文将介绍SpringBoot和Swagger2的常用注解。

2. 添加依赖

2.1 引入SpringBoot依赖

首先，在你的SpringBoot项目的pom.xml文件中，添加以下依赖：


<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

2.2 引入Swagger2依赖

接着，添加Swagger2的依赖：


<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>

3. 配置Swagger2

下一步是配置Swagger2。在SpringBoot的配置类中添加Swagger2的相关配置：


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

在这个配置类中，使用了@EnableSwagger2注解开启Swagger2的自动配置。Docket对象定义了Swagger2的文档配置信息。

上面的配置将扫描com.example.controller包下的所有Controller类，并生成相应的接口文档。

4. 添加Swagger2注解

4.1 添加@Api注解

在Controller类上添加@Api注解，用于对该类进行标注。这个注解可以用于描述整个Controller的功能、说明等信息。


@RestController
@Api(tags = "用户管理相关接口")
public class UserController {
   //...
}

上面的例子中，标注了一个"用户管理相关接口"的标签。

4.2 添加@ApiOperation注解

在Controller的方法上添加@ApiOperation注解，用于对该方法进行标注。这个注解可以用于描述方法的功能、用途等信息。


@GetMapping("/user/{id}")
@ApiOperation(value = "根据ID获取用户信息", notes = "根据用户ID来获取用户详细信息")
public User getUserById(@PathVariable Long id) {
    //...
}

上面的例子中，标注了一个"根据ID获取用户信息"的标签，并在注解的value属性中说明了该方法的用途。

4.3 添加@ApiParam注解

在Controller的方法参数上添加@ApiParam注解，用于对该参数进行标注。这个注解可以用于描述参数的用途、限制等信息。


@GetMapping("/user")
@ApiOperation(value = "根据条件获取用户列表", notes = "根据条件查询用户列表")
public List<User> getUsers(
    @ApiParam(value = "用户名") @RequestParam(required = false) String username,
    @ApiParam(value = "年龄") @RequestParam(required = false) Integer age) {
    //...
}

上面的例子中，标注了两个参数username和age，并在注解的value属性中说明了这两个参数的用途。

5. 访问Swagger2 UI

完成上述步骤后，启动SpringBoot应用程序，在浏览器中访问http://localhost:8080/swagger-ui.html即可看到Swagger2的UI界面。

在界面中，可以查看所有接口的详细信息，包括接口的URL、请求方法、参数列表、请求示例等。

6. 总结

本文介绍了SpringBoot和Swagger2的常用注解。通过使用这些注解，我们可以更加方便地编写和管理接口文档，提高开发效率和接口的可读性。希望本文对你在使用SpringBoot和Swagger2进行接口开发有所帮助。

SpringBoot+Swagger2常用注解