SpringBoot(7)整合swagger

---

一、swagger是什么

1、是一款让你更好的书写API文档的规范且完整框架。

2、提供描述、生产、消费和可视化RESTful Web Service。

3、是由庞大工具集合支撑的形式化规范。这个集合涵盖了从终端用户接口、底层代码库到商业API管理的方方面面

二、springboot集成swagger

1、导入依赖

 <dependency>
            <groupId>io.springfoxgroupId>
            <artifactId>springfox-swagger2artifactId>
            <version>2.9.2version>
        dependency>
        <dependency>
            <groupId>io.springfoxgroupId>
            <artifactId>springfox-swagger-uiartifactId>
            <version>2.9.2version>
        dependency>

2、配置文件

package com.buba.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwagerrConfiguration {
     private static ApiInfo DEFAULT = null;
     @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2);
    }
}

3、解决 高版本SpringBoot整合Swagger 启动报错Failed to start bean ‘documentationPluginsBootstrapper‘ 问题

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

4、访问swagger

http://127.0.0.1:8081/swagger-ui.html#/

三、swagger信息配置

package com.buba.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;

@Configuration
@EnableSwagger2
public class SwagerrConfiguration {
    private static ApiInfo DEFAULT = null;
    @Bean
    public Docket docket(){
        Contact DEFAULT_CONTACT = new Contact("qlx", "http://www.buba.com", "[email protected]");
        DEFAULT = new ApiInfo(
                "qlx的开发接口",
                "Api Documentation",
                "V-1.0",
                "http://www.buba.com",
                DEFAULT_CONTACT,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(DEFAULT);

    }
}

四、swagger配置接口

1、apis(RequestHandlerSelectors.basePackage(“com.example.demo2.controller”))//按照包名扫描
2、apis(RequestHandlerSelectors.any())全部扫面
3、apis(RequestHandlerSelectors.none())不扫面
4、paths(PathSelectors.ant(“controller”))//过滤指定包下的接口

package com.buba.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;

@Configuration
@EnableSwagger2
public class SwagerrConfiguration {
    private static ApiInfo DEFAULT = null;
    @Bean
    public Docket docket(){
        Contact DEFAULT_CONTACT = new Contact("qlx", "http://www.baidu.com", "[email protected]");
        DEFAULT = new ApiInfo("qlx的开发接口",
                "Api Documentation",
                "V-1.0",
                "http://www.buba.com",
                DEFAULT_CONTACT,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(DEFAULT)
                .select()
                //.apis(RequestHandlerSelectors.basePackage("com.buba.controller"))//按照包名扫描
                //.apis(RequestHandlerSelectors.any())全部扫面
                //.apis(RequestHandlerSelectors.none())不扫面
                // .paths(PathSelectors.ant("controller"))//过滤指定包下的接口
                .build();
    }
}

五、配置springboot环境（开发|生产）

spring:
  profiles:
    active: dev

六、swagger关闭

package com.buba.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;

@Configuration
@EnableSwagger2//开启swagger
public class SwagerrConfiguration {
    private static ApiInfo DEFAULT = null;
    @Bean//创建swagger实例
    public Docket docket(Environment environment){
        Contact DEFAULT_CONTACT = new Contact("qlx", "http://www.buba.com", "[email protected]");
        DEFAULT = new ApiInfo("qlx的开发接口",
                "Api Documentation",
                "V-1.0",
                "http://www.buba.com",
                DEFAULT_CONTACT,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
        Profiles profiles = Profiles.of("dev");//设置在那个环境下显示swagger,这里设置环境为dev时显示
        boolean b = environment.acceptsProfiles(profiles);//判断是不是现在的环境是不是我们想要的环境
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(DEFAULT)
                .enable(b)//配置swagger是否开启，如果为false则关闭swagger，默认为true
                .select()
                .build();
    }
}

表示关闭swagger,如果有两个swgger,其中一个打开的，那么不会出现这个试图，而是只显示没有关闭的那个swagger.

七、swagge分组

简单来说就是创建多个docket，并用groupName（“name”）指明是谁的

package com.buba.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;
@Configuration
@EnableSwagger2//开启swagger
public class SwagerrConfiguration {
    private static ApiInfo DEFAULT = null;
    @Bean//创建swagger实例
    public Docket docket(Environment environment){
        Contact DEFAULT_CONTACT = new Contact("lisi", "http://www.baidu.com", "[email protected]");
        DEFAULT = new ApiInfo("lisi的开发接口",
                "Api Documentation",
                "V-1.0",
                "http://www.baidu.com",
                DEFAULT_CONTACT,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
        Profiles profiles = Profiles.of("dev");//设置在那个环境下显示swagger
        boolean b = environment.acceptsProfiles(profiles);//获得项目的环境
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(DEFAULT)
                .groupName("lisi")
                .enable(b)//配置swagger是否开启，如果为false则关闭swagger，默认为true
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.buba.mappers"))//按照包名扫描
                .build();
    }
    @Bean//创建swagger实例
    public Docket docket1(Environment environment){
        Contact DEFAULT_CONTACT = new Contact("zhangsan", "http://www.baidu.com", "[email protected]");
        DEFAULT = new ApiInfo("zhangsan开发接口",
                "Api Documentation",
                "V-1.0",
                "http://www.buba.com",
                DEFAULT_CONTACT,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
        Profiles profiles = Profiles.of("dev");//设置在那个环境下显示swagger
        boolean b = environment.acceptsProfiles(profiles);//获得项目的环境
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(DEFAULT)
                .groupName("zhangsan")
                .enable(b)//配置swagger是否开启，如果为false则关闭swagger，默认为true
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.buba.controller"))//按照包名扫描
                .build();
    }
}

八、swagger注解

1、用于 controller 类上:

@API: 放在 请求的类上, 与 @Controller 并列, 说明类的作用, 如用户模块, 订单类等.
tags=“说明该类的作用” value=“该参数没什么意义, 所以不需要配置”

@API(tags="订单模块")
@Controller
public class OrderController {	
}

@API 其它属性配置:

2、用于方法上面 (说明参数的含义):

@ApiOperation:"用在请求的方法上, 说明方法的作用" value="说明方法的作用" notes="方法的备注说明"

  @ApiOperation("上传人脸比对已存在的人脸")
    @PostMapping("/upload")
    public Result upload(@RequestHeader String token,@RequestParam("file") MultipartFile fileUpload) throws Exception{}

@ApiImplicitParams,@ApiImplicitParam: 方法参数的说明
@ApiImplicitParams: 用在请求的方法上, 包含一组参数说明
@ApiImplicitParam: 对单个参数的说明
name: 参数名
value: 参数的汉字说明, 解释
required: 参数是否必须传
paramType: 参数放在哪个地方
. header --> 请求参数的获取:@RequestHeader
. query --> 请求参数的获取:@RequestParam
. path(用于 restful 接口)–> 请求参数的获取:@PathVariable
. dataType: 参数类型, 默认 String, 其它值 dataType=“Integer”
. defaultValue: 参数的默认值

示列:

@API(tags="用户模块")
@Controller
public class UserController {
    @ApiOperation(value="用户登录",notes="随边说点啥")
    @ApiImplicitParams({
        @ApiImplicitParam(name="mobile",value="手机号",required=true,paramType="form"),
        @ApiImplicitParam(name="password",value="密码",required=true,paramType="form"),
        @ApiImplicitParam(name="age",value="年龄",required=true,paramType="form",dataType="Integer")
    })
    @PostMapping("/login")
    public JsonResult login(@RequestParam String mobile, @RequestParam String password,
    @RequestParam Integer age){
        //...
        return JsonResult.ok(map);
    }
}

3、用于方法上面 (返回参数或对象的说明):

4、对象类: