swagger集成springboot，（一篇让你瞬间精通swagger2.9.2的文章）

一，导入相关依赖

　　maven下载：springfox.swagger2，springfox.swaggerUI

　　或者在springboot项目中，直接导入一个依赖springfox-boot-starter（目前最新版本3.0.0）

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

注意：这里我用到时swagger2.9.2版本，建议使用swagger3.0.0的

　　　swagger3.0.0是当前最新版本，它简化了swagger2.9.2的部分操做，如号称“零配置”，那么问题来了，博主为何没有直接学swagger3呢？

　　　　由于swagger3目前仍是有一些不足的，且博主能力有限，不可以直接看源码就能学懂，因此我选择学swagger2（网上教学ziyuanduo），

　　　　还有一个就是swagger2和3其实也没差多少，博主打算swagger3更稳定的时候在看一遍就好了hhhhh

 

二，配值swagger，（编写配置类）

1.集成springboot（没有自定义，那么都走默认的）

@Configuration
@EnableSwagger2  //开启swagger2
public class SwaggerConfig {

}

 

2.测试：请求http://localhost:8080/swagger-ui.html

 

 

 

 

 

2.配置swagger的docket的bean实例对象docket（核心时文档插件）

2.1，docket的bean实例来源核心

 

 

 

2.2Swagger的接口初始化配置

　　Docket.apiInfo()

@Configuration
@EnableSwagger2  //开启swagger2
public class SwaggerConfig {

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

    private ApiInfo apiInfo(){

        //存放做者信息
        Contact contact = new Contact("king", "https://www.cnblogs.com/CL-King/", "3342239623@qq.com");

        return new ApiInfo(
                "king的Swagger API文档",
                "测试！测试！",
                "1.0",
                "https://www.cnblogs.com/CL-King/",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }

}

 

2.3，Swagger配置扫描接口

　　Docket.select()

    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                //requestHandlerSelector配置要扫描接口的方式
                .apis(RequestHandlerSelectors.basePackage("com.king.swagger.controller"))//basePackage基于某个包去扫描
                .build();
    }

2.4,过滤什么路径

　　Docket.paths()

    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)//paths()过滤什么路径,只扫描自定义路径的接口
                .paths(PathSelectors.ant("/user/**"))
                .build();
    }

 

2.5，自动启动swagger

　　Docket.enable(),默认时true

2.6，Swagger的经常使用完整配置

　　补充：分组，Docket.groupName("name")

　　实现多个分组：注册多个bean就能够了

 

 

Swagger的经常使用完整配置

    //配置Swagger的Docket的bean实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(false)//enab是否启动Swagger，默认true
                .select()
                //requestHandlerSelector配置要扫描接口的方式
                .apis(RequestHandlerSelectors.basePackage("com.king.swagger.controller"))//basePackage基于某个包去扫描
                //paths()过滤什么路径,只扫描自定义路径的接口
                /*.paths(PathSelectors.ant("/user/**"))*/
                .build();
    }

 

问题：如何让swagger在开发环境中启用，在上线环境下关闭？

思路：多环境配置，（一个开发环境dev，一个发布环境pro），

　　　经过判断所处环境，给Docket.enable()赋值；

扩展：由于enable要的时boolean值，

　　　方法一：因此能够才环境配置文件中写死，在swagger配置类中获取最后传给Docket.enable（）

　　　方法二：也能够经过子swagger类中写死开启swagger的环境的方式来实现

　　　实现写的是方法二的代码，方法一简单就不去写了

实现：

    //配置Swagger的Docket的bean实例
    @Bean
    public Docket docket(Environment environment){

        //设置要开启swagger的环境
        Profiles profiles = Profiles.of("dev", "test");

        //经过environment.acceptsProfiles（）方法判断是否处于设定环境
        boolean b = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(b)//enab是否启动Swagger，默认true
                .select()
                //requestHandlerSelector配置要扫描接口的方式
                .apis(RequestHandlerSelectors.basePackage("com.king.swagger.controller"))//basePackage基于某个包去扫描
                //paths()过滤什么路径,只扫描自定义路径的接口
                /*.paths(PathSelectors.ant("/user/**"))*/
                .build();
    }

 

3，实体类配置（待更）

问题：swagger如何与实体类创建关联

解答：在controller层，放回的值只要包含实体类，swagger就会检测到该实体类

    //只要接口的返回值中存在实体类，该实体类就会被swagger扫描到
    @GetMapping(value = "/user")
    public User user(){

        return new User();
    }

 

swagger关于实体类的注解：

@ApiModel：给实体类加注释经过Swagger，做用在类上

@ApiModelProperty：给实体类的字段加注释经过Swagger，做用在字段上

//给实体类加注释经过Swagger，做用在类上
@ApiModel("用户实体类")
public class User {

    //给实体类的字段加注释经过Swagger，做用在字段上
    @ApiModelProperty("用户名")
    public String username;
    @ApiModelProperty("密码")
    public String password;

}

 

 

 

 

 问题：细心的同窗会发现，个人实体类demo的字段属性是public当改为private后，swagger就检测不到了，怎么办？

解答：很简单，经过相对应的get方式就能够啦，有这个问题的建议去看javase基础，这是类字段属性访问权限问题，这里写public是为了方便测试

 

swagger关于controller层的注解：

@ApiOperation（”xx“）做用子在方法上

@ApiParam("xx")做用方法传参位置

    //@ApiOperation做用子在方法上
    @ApiOperation("Hello控制类")
    @GetMapping(value = "/hello2")
    public String hello2(@ApiParam("用户名") String username){

        return "hello"+username;
    }

扩展：接口测试

1.找到要测试接口（请求），点击try it out

 

 

输入测试参数后，点击Execute

 

 

 

swagger优势：

　　1.经过swagger给项目中难理解的属性和接口加注解，方便接口测试的可读性，提升效率

　　2.接口文档实时更新

　　3.能够在线测试

Swagger是一个很是优秀的框架，几乎全部成规模的公司都会使用它

注意：为确保项目安全，s项目正式发布是要关闭swagger，也节省运行内存