关于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@EnableSwagger2public class SwaggerConfig{}

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

默认成果

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

2、配置

在以上配置类中增加办法：

//配置swagger的Docket的Bean实例@Beanpublic 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，然而生产环境不应用：

@Beanpublic 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")

配置多个分组：

@Beanpublic Docket docketGroupA(){    return new Docket(DocumentationType.SWAGGER_2).groupName("A");}@Beanpublic Docket docketGroupB(){    return new Docket(DocumentationType.SWAGGER_2).groupName("B");}@Beanpublic 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;}