SpringBoot整合Swagger2

2022-05-15 16:30:30

Our-task介绍

本篇博客是我github上our-task：一个完整的清单管理系统的配套教程文档，这是SpringBoot+Vue开发的前后端分离清单管理工具，仿滴答清单。目前已部署在阿里云ECS上，可进行在线预览，随意使用（附详细教程），大家感兴趣的话，欢迎给个star!

阿里云预览地址

整合步骤

maven依赖

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

    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
    <!--Swagger-UI API文档生产工具-->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.7.0</version>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.7.0</version>
    </dependency>
</dependencies>

User实体

新建User类，方便后续验证配置是否正确，其中

@ApiModelProperty用于方法，字段；表示对model属性的说明或者数据操作更改。

public class User{

    @ApiModelProperty(value = "用户id")
    Integer id;

    @ApiModelProperty(value = "用户姓名")
    String username;

    @ApiModelProperty(value = "用户密码")
    String password;

    public User(String username, String password) {
        this.username = username;
        this.password = password;
    }

    @Override
    public String toString() {
        return "User{" +
                "username='" + username + '\'' +
                ", password='" + password + '\'' +
                '}';
    }

    public Integer getId() {
        return id;
    }

    public void setId(Integer id) {
        this.id = id;
    }

    public String getUsername() {
        return username;
    }

    public void setUsername(String username) {
        this.username = username;
    }

    public String getPassword() {
        return password;
    }

    public void setPassword(String password) {
        this.password = password;
    }
}

Swagger-UI配置类

大家只需要修改其中的basePackage("com.example.demo.controller")，把这个改为自己的controller层的包名就可以了，Swagger-UI就会扫描该包下所有的Controller，从而显示在前段界面上。

@Configuration
@EnableSwagger2
public class Swagger2Config {
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //为当前包下controller生成API文档
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("配置SwaggerUI")
                .description("Swagger-UI-Demo")
                .version("1.0")
                .build();
    }
}

UserController

@RestController
@Api(value = "用户控制器", tags = {"用户操作"})
public class UserController {
    @GetMapping("/hello")
    @ApiOperation("打招呼")
    public String hello(){
        return "你好，我是小娜";
    }

    @PostMapping("/login")
    @ApiOperation("登录")
    public String login(@RequestBody @ApiParam("用户对象") User user){
        return "你好" + user.toString();
    }
}

注解含义说明

@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiProperty：用对象接收参数时，描述对象的一个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息
@ApiImplicitParam：描述一个请求参数，可以配置参数的中文含义，还可以给参数设置默认值
@ApiImplicitParams：描述由多个 @ApiImplicitParam 注解的参数组成的请求参数列表

配套代码

写了这么多，还是担心大家出现问题解决不了，所以我把配套Demo放在github上了，大家有问题可以的话可以去下载运行看看。

Swagger-UI-Demo

码农公寓