关于springboot:Spring-boot-接入swagger以及使用

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