springboot中Swagger的使用和注解

项目中会用到，但是有些细节老是忘掉，索性做个记录吧

一、依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.2.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.2.2</version>
</dependency>

二、新建swagger配置类


@Configuration
@EnableSwagger2
public class SwaggerConfig {
    /**
     * 创建API应用
     * apiInfo() 增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
     * 本例采用指定扫描的包路径来定义指定要建立API的目录。
     *
     * @return
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //api接口包扫描路径
.apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 创建该API的基本信息（这些基本信息会展现在文档页面中）
     * 访问地址：http://项目实际地址/swagger-ui.html
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("xxx项目")
                .description("xxx项目描述")
                .termsOfServiceUrl("https://www.cnblogs.com/liconglong/")
             	.contact(new Contact("surfingYu", "http://surfingyu.top/", "wxvew3@126.com"))
                .version("1.0")
                .build();
    }
}

到此配置完成，后面是注解说明

三、注解使用

先上示例代码

controller

@Api(tags = {"订单相关接口"})
@RestController
@RequestMapping("im/order")
public class ImOrderController extends BaseComponent {

    @Autowired
    private EcRequestService requestService;

    @ApiOperation(value = "获取可选号码列表", notes = "获取可选号码列表",tags = "tags")
    @GetMapping("qryNum")
    public JsonResponse qryNum(@ApiParam(value = "页码",required = true) @RequestParam(name = "pageNum", required = false)Integer pageNum,
                               @ApiParam("匹配号码段") @RequestParam(name = "matchNumber", required = false)String  matchNumber) throws Exception{
        Map<String, Object> map = new HashMap<String, Object>(2){{
            put("pageNum",pageNum == null?1:pageNum);
            put("matchNumber", "".equals(matchNumber)?"":matchNumber);
        }};
        return super.successed(requestService.EcQryNum(map));
    }
    @ApiOperation(value = "创建个人信息", notes = "创建个人信息")
    @PostMapping("addPersonInfo")
    public JsonResponse addPersonInfo(@Validated AddPersonInfoQo addPersonInfoQo) throws Exception{
        return super.successed(requestService.EcAddPersonInfo(addPersonInfoQo));
    }
}


@ApiModel(value = "创建个人信息对象")
public class AddPersonInfoQo {

    @NotNull
    @ApiModelProperty(value = "姓氏")
    private String firstName;

    @NotNull
    @ApiModelProperty(value = "名字")
    private String lastName;

    @ApiModelProperty(value = "性别")
    private String sex;

    @NotNull
    @ApiModelProperty(value = "联系电话")
    private String contactPhone;

    @NotNull
    @ApiModelProperty(value = "证件号码")
    private String cardNo;

    @NotNull
    @ApiModelProperty(value = "证件类型")
    private String cardType;

    @NotNull
    @ApiModelProperty(value = "证件有效期",example = "1986/01/01")
    private String cardLimit;

    @NotNull
    @ApiModelProperty(value = "生日", example = "2021/12/12")
    private String birthday;

    }

上面接口示例了@Api @ApiOperation @ApiParam @ApiModel @ApiModelProperty的使用，下面简单说明swagge注释：

@Api

修饰整个类，描述Controller的作用
参数：
tags–说明
value–也是说明，可以使用tags替代
但是tags如果有多个值，会生成多个list

@ApiOperation

描述一个类的一个方法，或者说一个接口
参数：
value-api名称
notes-说明
tags-可以重新分组

@ApiParam

单个参数描述
参数：
name–参数名
value–参数说明
required–是否必填
👀这里需要注意一下👀
我在示例代码里面同时使用了@ApiParam和spring的@RequestParam来配置required属性
在@RequestParam这里默认required为true，@ApiParam是默认为false，如果同时使用了这两个注解，required属性值默认使用@RequestParam里面的required属性，如果没有设置就默认为true，也就是必填

@ApiModel

表示对类进行说明，用于参数用实体类接收
参数：
value–对象名
description–描述

@ApiModelProperty

用对象接收参数时，描述对象的一个方法，字段；
value–字段说明
name–重写属性名字
dataType–重写属性类型
required–是否必填
example–举例说明
hidden–隐藏

@ApiIgnore

用于类或者方法上，可以不被swagger显示在页面上

@ApiImplicitParam

用于方法,表示单独的请求参数,可以配置参数的中文含义，还可以给参数设置默认值
参数
name–参数ming
value–参数说明
dataType–数据类型
paramType–参数类型
example–例子

@ApiImplicitParams

用于方法,描述由多个 @ApiImplicitParam 注解的参数组成的请求参数列表

四、启动项目

启动项目，访问你的项目地址/swagger-ui.html即可看到

点击其中一个可查看接口详细描述、出入参等信息

其他

Spring Boot 项目中如果集成了 Spring Security，在不做额外配置的情况下，Swagger2 文档会被拦截。解决方法是在 Security 的配置类中重写 configure 方法添加白名单即可：

@Override
public void configure ( WebSecurity web) throws Exception {
    web.ignoring()
      .antMatchers("/swagger-ui.html")
      .antMatchers("/v2/**")
      .antMatchers("/swagger-resources/**");
}

目录CONTENT