Spring Boot 2.0

Spring Boot 集成 swagger2

2019-12-12  本文已影响0人  AaronSimon

在开发过程中，为了实现前后端高效的沟通，通常需要提供相关的接口文档。

Swagger2可以轻松的整合到SpringBoot中，并与SpringMVC程序配合组织出强大RESTful API文档。它既可以减少我们创建文档的工作量，也可以让我们在修改代码逻辑的同时修改文档说明。此外Swagger2也提供了强大的页面测试功能来调试每个RESTful API。

本文主要介绍Spring Boot 2.0 与 Swagger2的整合。

一、swagger 注解

@Api：用在请求的类上，表示对类的说明
    tags="说明该类的作用，可以在UI界面上看到的注解"
    value="该参数没什么意义，在UI界面上也看到，所以不需要配置"

@ApiOperation：用在请求的方法上，说明方法的用途、作用
    value="说明方法的用途、作用"
    notes="方法的备注说明"

@ApiImplicitParams：用在请求的方法上，表示一组参数说明
    @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
        name：参数名
        value：参数的汉字说明、解释
        required：参数是否必须传
        paramType：参数放在哪个地方
            · header --> 请求参数的获取：@RequestHeader
            · query --> 请求参数的获取：@RequestParam
            · path（用于restful接口）--> 请求参数的获取：@PathVariable
            · body（不常用）
            · form（不常用）    
        dataType：参数类型，默认String，其它值dataType="Integer"       
        defaultValue：参数的默认值

@ApiResponses：用在请求的方法上，表示一组响应
    @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
        code：数字，例如400
        message：信息，例如"请求参数没填好"
        response：抛出异常的类

@ApiModel：用于类上，表示一组数据的信息
            （这种一般用在post创建的时候，使用@RequestBody这样的场景，
            请求参数无法使用@ApiImplicitParam注解进行描述的时候）
    @ApiModelProperty：用在属性上，描述属性

二、添加依赖

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

三、配置Swagger

package pers.simon.boot.validator.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.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * swagger2 配置
 *
 * @author simon
 * @date 2019/12/12 13:57
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    /**
     * 实例化一个 Docket Bean
     * <p></p>
     * <b>
     * 这个Bean中，配置映射路径和要扫描的接口的位置，在apiInfo中，主要配置一下Swagger2文档网站的信息，例如网站的title，网站的描述，联系人的信息，使用的协议等等
     * </b>
     *
     * @return Docket Bean
     */
    @Bean
    public Docket createDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .pathMapping("/")//默认请求都是以 / 根路径开始，如果我们的应用不是部署在根路径，比如以/validator部署，则可以通过一下方式设置请求的统一前缀
                .select()
                .apis(RequestHandlerSelectors.basePackage("pers.simon.boot.validator.controller"))//
                .paths(PathSelectors.any())
                .build()
                .apiInfo(new ApiInfoBuilder()
                        .title("Spring Boot 参数校验")
                        .description("使用 validator 对入参进行校验。包含自定义规则校验，分组校验，全局异常处理等")
                        .version("1.0.0")
                        .contact(new Contact("simon", "www.baidu.com", "simon@126.com"))
                        .license("The Apache License")
                        .licenseUrl("www.baidu.com")
                        .build()
                );

    }
}

四、接口

package pers.simon.boot.validator.controller;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.*;
import pers.simon.boot.validator.annotate.Create;
import pers.simon.boot.validator.annotate.Update;
import pers.simon.boot.validator.po.UserVo;
import pers.simon.boot.validator.utils.JsonResult;

import javax.validation.constraints.NotEmpty;

/**
 *
 * @author simon
 * @date 2019/12/10 10:39
 */
@Api(tags = "用户管理")
@RestController
@Validated
public class UserController {

    @ApiOperation("添加用户")
    @PostMapping("/user")
    @ApiImplicitParam(name = "userVo", value = "用户信息表单", required = true, dataType = "UserVo")
    public JsonResult saveUser(@RequestBody @Validated(Create.class) UserVo userVo){
        return JsonResult.success(userVo);
    }

    @ApiOperation("修改用户")
    @ApiImplicitParam(name = "userVo", value = "用户信息表单", required = true, dataType = "UserVo")
    @PutMapping("/user")
    public JsonResult updateUser(@RequestBody @Validated(Update.class) UserVo userVo){
        return JsonResult.success(userVo);
    }

    @ApiOperation("注销用户")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "userId",value = "用户ID",defaultValue = "",required = true),
            @ApiImplicitParam(name = "deptId",value = "部门ID",defaultValue = "",required = true)
    })
    @PatchMapping("/user")
    public JsonResult disableUser(@NotEmpty(message = "用户ID不能为空")String userId, @NotEmpty(message = "所属部门ID不能为空")String deptId){
        return JsonResult.success(userId);
    }
}

入参UserVo

package pers.simon.boot.validator.po;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import pers.simon.boot.validator.annotate.Create;
import pers.simon.boot.validator.annotate.IdCard;
import pers.simon.boot.validator.annotate.Update;

import javax.validation.constraints.*;
import java.util.Date;

/**
 * @author simon
 * @date 2019/12/10 10:28
 */
@ApiModel(description = "用户信息表单")
@Data
public class UserVo {

    @ApiModelProperty(value = "用户ID", name = "userId", required = true, example = "123")
    @Null(message = "用户ID必须为空",groups = Create.class)
    @NotBlank(message = "用户ID不能为空",groups = Update.class)
    private String userId;

    @ApiModelProperty(value = "用户名称", name = "userName", required = true, example = "admin")
    @NotBlank(message = "用户名不能为空")
    private String userName;

    @ApiModelProperty(value = "生日", name = "birthday", required = true, example = "2019-11-02")
    @Past(message = "生日必须为过去日期")
    @NotNull(message = "生日不能为空")
    private Date birthday;

    @ApiModelProperty(value = "年龄", name = "age", required = true, example = "11", dataType = "int")
    @Min(value = 10,message = "年龄必须大于10")
    @Max(value = 30,message = "年龄必须小于30")
    @NotNull(message = "年龄不能为空")
    private Integer age;

    @ApiModelProperty(value = "邮箱", name = "email", required = true, example = "11@qq.com")
    @NotBlank(message = "邮箱不能为空")
    @Email(message = "邮箱格式错误")
    private String email;

    @ApiModelProperty(value = "手机号", name = "phone", required = true, example = "12345678900")
    @NotNull(message = "手机号不能为空")
    @NotBlank(message = "手机号不能为空")
    @Pattern(regexp ="^[1][3,4,5,6,7,8,9][0-9]{9}$", message = "手机号格式有误")
    @Max(value = 11,message = "手机号只能为11位")
    @Min(value = 11,message = "手机号只能为11位")
    private String phone;

    @ApiModelProperty(value = "身份证号", name = "idCard", required = true, example = "12345678900")
    @NotBlank(message = "身份证不能为空")
    @IdCard(message = "身份证不合法")
    private String idCard;
}

六、测试

访问：http://localhost:8080/swagger-ui.html

2aa6d12ee2d2ad060698cce87e45a6c.png
上一篇下一篇

猜你喜欢

热点阅读