Spring Boot 集成 swagger2

更新时间:2019-12-16 11:04:08 点击次数:177次
在开发过程中,为了实现前后端高效的沟通,通常需要提供相关的接口文档。

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

本站文章版权归原作者及原出处所有 。内容为作者个人观点, 并不代表本站赞同其观点和对其真实性负责,本站只提供参考并不构成任何投资及应用建议。本站是一个个人学习交流的平台,网站上部分文章为转载,并不用于任何商业目的,我们已经尽可能的对作者和来源进行了通告,但是能力有限或疏忽,造成漏登,请及时联系我们,我们将根据著作权人的要求,立即更正或者删除有关内容。本站拥有对此声明的最终解释权。

回到顶部
嘿,我来帮您!