文章目录

零项目源码
一 Swagger简介
二 Spring Boot集成Swagger
- 2.1 环境准备
- 2.2 配置Swagger
- 2.3 配置文档信息
- 2.4 配置扫描接口
- 2.5 配置开关Swagger
- 2.6 配置API分组
- 2.7 配置实体类
- 2.8 常用注解

在这里插入图片描述

零项目源码

Swagger源码免费下载

一 Swagger简介

Swagger官网
swagger是一款可以根据resutful风格生成的生成的接口开发文档，并且支持做测试的一款中间软件。
Swagger是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。
Swagger是一个规范和完整的框架,用于生成、描述、调用和可视化RESTful风格的Web服务。
目标：使客户端和文件系统作为服务器以同样的速度来更新文件的方法,参数和模型紧密集成到服务器。
支持多种语言（如：Java，PHP等）

注意：在正式环境要记得关闭Swagger，一方面出于安全考虑，另一方方面可以节省运行时内存

二 Spring Boot集成Swagger

2.1 环境准备

合适的版本匹配

JDK1.8+
spring boot 2.5.6/2.5.7
springfox-swagger-ui 2.9.2

springfox-swagger2 2.9.2

 <!-- 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>

否则会出现版本冲突出现空指针异常问题

Failed to start bean 'documentationPluginsBootstrapper'; 
nested exception is java.lang.NullPointerException

2.2 配置Swagger

编写HelloController类，进行测试

@RestController
public class HelloController {
    @RequestMapping("/hello")
    public String hello() {
        return "Hello";
    }
}

编写配置类SwaggerConfig

@Configuration //配置类
@EnableSwagger2// 开启Swagger2的自动配置
public class SwaggerConfig {

}

2.3 配置文档信息

配置Docket实例

Swagger实例Bean是Docket，所以通过配置Docket实例来配置Swaggger

//配置docket以配置Swagger具体参数
@Bean 
public Docket docket() {
	return new Docket(DocumentationType.SWAGGER_2);
}

配置ApiInfo属性文档信息

//配置swagger文档信息apiInfo
    private ApiInfo apiInfo() {
        //作者信息
        Contact contact = new Contact("缘友一世", "https://www.csdn.net/", "xxxxxxxxx@qq.com");
        return new ApiInfo(
                "Spring Boot集成Swagger",//标题
                "学习Swagger",//描述
                "1.0",//版本
                "http://localhost",//组织连接
                contact,//联系人信息
                "Apache 2.0",//许可
                "http://www.apache.org/licenses/LICENSE-2.0",//许可连接
                new ArrayList());//拓展
    }

记得修改Docket的内容

@Bean 
public Docket docket() {
	return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
}

2.4 配置扫描接口

通过select()方法配置扫描接口

@Bean
public Docket docket() {
	return new Docket(DocumentationType.SWAGGER_2)
	.apiInfo(apiInfo())
	// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
	.select()
	//RequestHandlerSelectors 配置扫描接口的方式
    //basePackage()：扫描指定的包 [主流]
    //any():扫描全部
    //none():不扫描
    //withClassAnnotation():扫描类上的注解 参数为注解的反射对象
    //withMethodAnnotation():扫描方法上的注解
    //.apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
    .apis(RequestHandlerSelectors.basePackage("com.yang.controller"))
	.build();
}

配置接口扫描过滤

 @Bean
public Docket docket1() {
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .groupName("A")
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.yang.controller"))
            //过滤路径
            /*
                any() // 任何请求都扫描
                none() // 任何请求都不扫描
                regex(final String pathRegex) // 通过正则表达式控制
                ant(final String antPattern) // 通过ant()控制
             */
            .paths(PathSelectors.ant("/yang/**"))
            .build();
}

2.5 配置开关Swagger

enable()方法，配置是否开启swagger

@Bean
public Docket docket() {
	return new Docket(DocumentationType.SWAGGER_2)
	.apiInfo(apiInfo())
	.enable(false) //配置是否启用Swagger，如果是false，在浏览器将无法访问
	.select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
	.apis(RequestHandlerSelectors.basePackage("com.yang.controller"))
	// 配置如何通过path过滤,即这里只扫描请求以/kuang开头的接口
	.paths(PathSelectors.ant("/yang/**"))
	.build();
}

由项目环境动态配置swagger

spring配置文件

#application.properties
spring.profiles.active=pro
#application-dev.properties
server.port=8081
#application-pro.properties
server.port=8080

//配置了swagger的docket的bean实例
//enable 是否开启swagger
@Bean
public Docket docket(Environment environment) {
    //设置要显示的Swagger环境
    Profiles profiles = Profiles.of("dev", "test");
    //获取项目的环境
    //通过environment.acceptsProfiles判断是否处于设定的环境中
    boolean flag = environment.acceptsProfiles(profiles);

    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .enable(flag)
            .groupName("缘友一世")
            .select()
            //RequestHandlerSelectors 配置扫描接口的方式
            //basePackage()：扫描指定的包 [主流]
            //any():扫描全部
            //none():不扫描
            //withClassAnnotation():扫描类上的注解 参数为注解的反射对象
            //withMethodAnnotation():扫描方法上的注解
            //.apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
            .apis(RequestHandlerSelectors.basePackage("com.yang.controller"))
            //过滤路径
            /*
                any() // 任何请求都扫描
                none() // 任何请求都不扫描
                regex(final String pathRegex) // 通过正则表达式控制
                ant(final String antPattern) // 通过ant()控制
             */
            .paths(PathSelectors.ant("/yang/**"))
            .build();
}

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

import java.util.ArrayList;

/**
 * @author 缘友一世
 * date 2023/1/27-21:25
 */
@Configuration
//开启swagger2
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket docket1() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("A")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.yang.controller"))
                //过滤路径
                /*
                    any() // 任何请求都扫描
                    none() // 任何请求都不扫描
                    regex(final String pathRegex) // 通过正则表达式控制
                    ant(final String antPattern) // 通过ant()控制
                 */
                .paths(PathSelectors.ant("/yang/**"))
                .build();
    }
    @Bean
    public Docket docket2() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("B");
    }
    @Bean
    public Docket docket3() {
        return new Docket(DocumentationType.SWAGGER_2).groupName("C");
    }
    //配置了swagger的docket的bean实例
    //enable 是否开启swagger
    @Bean
    public Docket docket(Environment environment) {
        //设置要显示的Swagger环境
        Profiles profiles = Profiles.of("dev", "test");
        //获取项目的环境
        //通过environment.acceptsProfiles判断是否处于设定的环境中
        boolean flag = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(flag)
                .groupName("缘友一世")
                .select()
                //RequestHandlerSelectors 配置扫描接口的方式
                //basePackage()：扫描指定的包 [主流]
                //any():扫描全部
                //none():不扫描
                //withClassAnnotation():扫描类上的注解 参数为注解的反射对象
                //withMethodAnnotation():扫描方法上的注解
                //.apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
                .apis(RequestHandlerSelectors.basePackage("com.yang.controller"))
                //过滤路径
                /*
                    any() // 任何请求都扫描
                    none() // 任何请求都不扫描
                    regex(final String pathRegex) // 通过正则表达式控制
                    ant(final String antPattern) // 通过ant()控制
                 */
                .paths(PathSelectors.ant("/yang/**"))
                .build();
    }
    //配置swagger文档信息apiInfo
    private ApiInfo apiInfo() {
        //作者信息
        Contact contact = new Contact("缘友一世", "https://www.csdn.net/", "xxxx@qq.com");
        return new ApiInfo(
                "Spring Boot集成Swagger",//标题
                "学习Swagger",//描述
                "1.0",//版本
                "http://localhost",//组织连接
                contact,//联系人信息
                "Apache 2.0",//许可
                "http://www.apache.org/licenses/LICENSE-2.0",//许可连接
                new ArrayList());//拓展
    }
}

在这里插入图片描述

2.6 配置API分组

通过groupName()方法即可配置分组

如果没有配置分组，默认是default

@Bean
public Docket docket(Environment environment) {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
	.groupName("hello") // 配置分组
	// 省略配置....
}

多个分组，需要配置多个docket

@Bean
public Docket docket1() {
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .groupName("A")
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.yang.controller"))
            //过滤路径
            /*
                any() // 任何请求都扫描
                none() // 任何请求都不扫描
                regex(final String pathRegex) // 通过正则表达式控制
                ant(final String antPattern) // 通过ant()控制
             */
            .paths(PathSelectors.ant("/yang/**"))
            .build();
}
@Bean
public Docket docket2() {
    return new Docket(DocumentationType.SWAGGER_2)
            .groupName("B");
}
@Bean
public Docket docket3() {
    return new Docket(DocumentationType.SWAGGER_2).groupName("C");
}

在这里插入图片描述

2.7 配置实体类

创建实体类

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

/**
 * @author 缘友一世
 * date 2023/1/28-10:21
 */

@ApiModel("用户实体类")
public class User {
    @ApiModelProperty("用户名")
    public String username;
    @ApiModelProperty("密码")
    public String password;
}

@ApiModel为类添加注释
@ApiModelProperty为类属性添加注释

请求接口映射到实体类
- 只要这个实体在请求接口的返回值上（即使是泛型），都能映射到实体项中
```
@RequestMapping("/getUser")
public User getUser(){
	return new User();
}
```
- 注：只要出现在接口方法的返回值上的实体都会显示，而@ApiModel和@ApiModelProperty这两个注解只是为实体添加注释的

2.8 常用注解

注解所在位置：io.swagger.annotations包下

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