Springboot 集成Swagger 2（springfox）

1、集成

导入依赖

Springfox Swagger2:

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>3.0.0</version>
</dependency>

Springfox Swagger UI:

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>3.0.0</version>
</dependency>

配置swagger

@Configuration
@EnableSwagger2
public class SwaggerConfig{}

创建一个以上一个类配置swagger即可。

默认效果

访问界面：IP:port/swagger-ui.html

2、配置

在以上配置类中添加方法：

//配置swagger的Docket的Bean实例
@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2).apiInfo(this.apiInfo());
}

//自定义swagger信息
private ApiInfo apiInfo(){
    Contact contact = new Contact("name","url","email");
    return new ApiInfo("title","description","version","termsOfServiceUrl",contact,"license",licenseUrl,new ArrayList());
}

3、配置扫描接口

项目中并不需要swagger将整个项目的所有类暴露出去，通过以上配置的Bean实例，设置swagger关注并显示的接口，以及是否开启使用：

return new Docket(DocumentationType.SWAGGER_2)
    .apiInfo(apiInfo())
    .enable(false)//false时，浏览器不能访问，默认为true
    .select()
    //RequestHandlerSelect，配置要扫描接口的方式
    //basePackage("包路径"):指定要扫描的包
    //any():全部扫描
    //none():不扫描
    //withClassAnnotation():扫描类上有指定的类注解的类，参数是一个类注解，如"RestContrller.class"
    //withMethodAnnotation():扫描方法上有指定的注解的方法，参数如"GetMapping.class"
    .api(RequestHandlerSelectors.basePackage("com.noel.swagger.controller"))
    //paths():过滤某些路径,参数为正则匹配参数
    .paths(PathSelectors.ant("/omit/**"))
    .build();

只希望在开发环境中使用swagger，但是生产环境不使用：

@Bean
public Docket docket(Environment environment){
    //dev: application-dev.yml or application-anotherEnv.yml 或者类似的properties配置文件
    //如果允许时加载了指定的环境，则返回true
    Profiles profiles = Profiles.of("dev","anotherEnv");
    Boolean isSwaggerOn = environment.acceptsProfiles(profiles);
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(this.apiInfo())
        .enable(isSwaggerOn);
}

配置API文档分组：

.group("groupName")

配置多个分组：

@Bean
public Docket docketGroupA(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("A");
}
@Bean
public Docket docketGroupB(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("B");
}
@Bean
public Docket docketGroupB(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("C");
}

在配置类中，一个Docket Bean实例，对应一个swagger分组。

4、常用注解

4.1、接口类的注解

4.1.1、接口类的使用

@Api：放在 请求的类上，与 @Controller 并列，说明类的作用，如用户模块，订单类等。

@Api的属性

示例：

@Api(value="/test", tags="测试接口")
@Controller
@RequestMapping("/test")
public class TestController{}

4.1.2、接口方法使用的注解说明

@ApiOperation："用在请求的方法上，说明方法的作用"
@ApiImplicitParams：用在请求的方法上，包含一组参数说明
@ApiImplicitParam：对单个参数的说明
name：参数名
value：参数的说明、描述
required：参数是否必须必填
paramType：参数放在哪个地方
query --> 请求参数的获取：@RequestParam
header --> 请求参数的获取：@RequestHeader
path（用于restful接口）--> 请求参数的获取：@PathVariable
body（请求体）--> @RequestBody User user
form（普通表单提交)
dataType：参数类型，默认String，其它值dataType="int"
defaultValue：参数的默认值
@ApiResponses：方法返回对象的说明
@ApiResponse：每个参数的说明
code：数字，例如400
message：信息，例如"请求参数没填好"
response：抛出异常的类

示例：

@ApiOperation(value="登录",notes="这是一个登录接口的说明")
@ApiImplicitParams({
    @ApiImplicitParam(name="name",value="姓名",required=true,paramType="form",dataType="String"),
    @ApiImplicitParam(name="age",value="年龄",required=true,paramType="form",dataType="int")
})
@ApiResponses({
    @ApiResponse(code = 200, message = "请求成功"),
    @ApiResponse(code = 400, message = "请求参数没填好"),
    @ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不存在")
}) 
@ResponseBody
@PostMapping("/login")
public JsonResult login(@RequestParam String name, @RequestParam Integer age){
    //...
    return JsonResult.ok(map);
}

4.2、实体类的注解

@ApiModel的用途有2个：
当请求数据描述，即 @RequestBody 时， 用于封装请求（包括数据的各种校验）数据；
当响应值是对象时，即 @ResponseBody 时，用于返回值对象的描述

@ApiModel的属性：

@ApiModelProperty的属性说明：

示例：

@ApiModel("用户")
Public class User{
    
    @ApiModelProperty("年龄")
    public Integer age;
    
    @ApiModelProperty(value="姓名", required=true)
    public String name;
}