# SpringBoot 整合 Swagger

SpringBoot 整合 Swagger

是什么不介绍，这个东西很简单，主要看点底层源码即可，

注意：这个东西很容易造成版本错乱的

部分引入 狂神说 的代码段，因为我有些东西懒得写

引入

<spring-boot.version>2.3.7.RELEASE</spring-boot.version>

我是临时发作想写教程，教程SpringBoot项目版本为 2.3.7 里程碑版

来个swagger 2.7.0的 gav：

<!--swagger-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.7.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.7.0</version>
</dependency>

配置

config里面创建swaggerConfig配置类：

package com.bihu.glxy.config;
 
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.RequestHandler;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
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;
 
@Configuration
@EnableSwagger2 // Swagger2自动配置开启
public class swaggerConfig {
 
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo("xxxx_Api文档", "1.1"))   //API 信息
                .select()   //配置怎么扫描接口
                .apis(RequestHandlerSelectors.basePackage("com.bihu.glxy.controller"))     //扫描器
                .paths(PathSelectors.ant("/glxy/**"))    //接口过滤器 即：这里只扫描请求以/glxy开头的接口
                .build();
    }
 
    /**
     * @param title   APi 标题
     * @param version Api 版本
     * @return ApiInfoBuilder 也可以返回APIInfo的，我觉得ApiInfoBuilder方便点。
     */
    private ApiInfo apiInfo(String title, String version) {
        return new ApiInfoBuilder()
                .title(title)
                .description("咸瑜的API文档")
                .termsOfServiceUrl("https://www.cnblogs.com/bi-hu/")
                .contact(new Contact("咸瑜", "https://www.cnblogs.com/bi-hu/", "1346174610@qq.com"))
                .version(version)
                .build();
    }
}

API 信息：

// 如果不写API信息 默认就是这个：
    static {
        DEFAULT = new ApiInfo("Api Documentation", "Api Documentation", "1.0", "urn:tos", DEFAULT_CONTACT, "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList());
    }

apis:扫描器参数选择：

any() // 扫描所有，项目中的所有接口都会被扫描到
none() // 不扫描接口
// 通过方法上的注解扫描，如withMethodAnnotation(GetMapping.class)只扫描get请求
withMethodAnnotation(final Class<? extends Annotation> annotation)
// 通过类上的注解扫描，如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
withClassAnnotation(final Class<? extends Annotation> annotation)
basePackage(final String basePackage) // 根据包路径扫描接口

paths：接口过滤器可选：

any() // 任何请求都扫描
none() // 任何请求都不扫描
regex(final String pathRegex) // 通过正则表达式控制
ant(final String antPattern) // 通过ant()控制

访问：http://localhost:8000/swagger-ui.html

配置Swagger开关

通过enable()方法配置是否启用swagger，如果是false，swagger将不能在浏览器中访问了，我们可以利用这个特点结合生产环境和其他环境显示和不显示：

.enable(false) //配置是否启用Swagger，如果是false，在浏览器将无法访问

@Bean
public Docket docket(Environment environment) {
    //获取环境
    boolean enableSwagger = environment.acceptsProfiles(Profiles.of("dev", "prod"));
 
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo("xxxx_Api文档", "1.1"))   //API 信息
            .enable(enableSwagger)	// !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
            .select()   //配置怎么扫描接口
            .apis(RequestHandlerSelectors.basePackage("com.bihu.glxy.controller"))     //扫描器
            .paths(PathSelectors.any())    //接口过滤器 即：这里只扫描请求以/glxy开头的接口
            .build();
}

如果没有 就给你这个就对了：

分组

@Bean
public Docket docket1(){
   return new Docket(DocumentationType.SWAGGER_2).groupName("group1");
}
@Bean
public Docket docket2(){
   return new Docket(DocumentationType.SWAGGER_2).groupName("group2");
}
@Bean
public Docket docket3(){
   return new Docket(DocumentationType.SWAGGER_2).groupName("group3");
}

可以设置多个组

实体配置

这个非常简单，直接用注解，这里不多写，直接上注解：

Swagger注解	简单说明
@Api(tags = "xxx模块说明")	作用在模块类上
@ApiOperation("xxx接口说明")	作用在接口方法上
@ApiModel("xxxPOJO说明")	作用在模型类上：如VO、BO
@ApiModelProperty(value = "xxx属性说明",hidden = true)	作用在类方法和属性上，hidden设置为true可以隐藏该属性
@ApiParam("xxx参数说明")	作用在参数、方法和字段上，类似@ApiModelProperty

皮肤

默认皮肤确实丑，可以用其他的：

bootstarp、Layui-ui、mg-ui ：【推荐mg-ui】

<!-- 默认的 -->
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger-ui</artifactId>
   <version>2.9.2</version>
</dependency>
 
<!-- 引入swagger-bootstrap-ui包 /doc.html-->
<dependency>
   <groupId>com.github.xiaoymin</groupId>
   <artifactId>swagger-bootstrap-ui</artifactId>
   <version>1.9.1</version>
</dependency>
 
<!-- 引入swagger-ui-layer包 /docs.html-->
<dependency>
   <groupId>com.github.caspar-chen</groupId>
   <artifactId>swagger-ui-layer</artifactId>
   <version>1.1.3</version>
</dependency>
 
<!-- 引入swagger-ui-layer包 /document.html-->
<dependency>
   <groupId>com.zyplayer</groupId>
   <artifactId>swagger-mg-ui</artifactId>
   <version>1.0.6</version>
</dependency>