Spring Boot之Swagger

编程语言 2023-01-29 01:04:42 阅读次数: 0

文章目录

在这里插入图片描述

零 项目源码

一 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

  1. 编写HelloController类，进行测试
    @RestController
public class HelloController {
      
      
    @RequestMapping("/hello")
    public String hello() {
      
      
        return "Hello";
    }
}
    在这里插入图片描述
  2. 编写配置类SwaggerConfig
    @Configuration //配置类
@EnableSwagger2// 开启Swagger2的自动配置
public class SwaggerConfig {
      
      

}
    在这里插入图片描述

2.3 配置文档信息

  1. 配置Docket实例
    • Swagger实例Bean是Docket，所以通过配置Docket实例来配置Swaggger
    //配置docket以配置Swagger具体参数
@Bean 
public Docket docket() {
      
      
	return new Docket(DocumentationType.SWAGGER_2);
}
  2. 配置ApiInfo属性文档信息
    //配置swagger文档信息apiInfo
    private ApiInfo apiInfo() {
      
      
        //作者信息
        Contact contact = new Contact("缘友一世", "https://www.csdn.net/", "[email protected]");
        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 配置扫描接口

  1. 通过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();
}
    在这里插入图片描述
  2. 配置接口扫描过滤
     @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

  1. 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();
}

  2. 由项目环境动态配置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/", "[email protected]");
        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分组

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

    • 如果没有配置分组，默认是default
    @Bean
public Docket docket(Environment environment) {
      
      
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
	.groupName("hello") // 配置分组
	// 省略配置....
}

  2. 多个分组，需要配置多个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 配置实体类

  1. 创建实体类

    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为类属性添加注释

  2. 请求接口映射到实体类

    • 只要这个实体在请求接口的返回值上（即使是泛型），都能映射到实体项中
    @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

猜你喜欢

转载自blog.csdn.net/yang2330648064/article/details/128776694
今日推荐
LFOSSA 源来如此公开课 | 掌握云原生未来：CNCF 认证全面攻略与备考秘籍
国产云输入法——仅华为无云端数据上传安全问题
开源日报 | 工业开源项目OGG 1.0；姐姐，你要和我一起配置火狐吗；苹果AI遥遥落后？Fedora 40
开放签电子签章：停止新增，优化体验，前进更进（五一假期前工作）
开源日报 | 中学生开源前端动画引擎；全球首个Llama3 8B中文版开源模型；联想电脑恐出局；Linus讽刺AI炒作
“百模大战”必有一战 | 2024中国“百模大战”竞争格局分析
周排行
Family Tree 题解
BZOJ 1093 最大半连通子图 SCC + DP
幂等处理
Spring----学习（2）----XML 配置Bean 自动装配
SQL Server 远程更新目标表数据
HIbernate3.6 环境搭建
特殊符号正则表达式
【Linux】第一章 进程的理解
843. n-皇后问题（dfs+输出各种情况）
空间数据库2
每日归档
更多
2024-04-26(39)
2024-04-25(22)
2024-04-24(36)
2024-04-23(26)
2024-04-22(39)
2024-04-21(0)
2024-04-20(6)
2024-04-19(5)
2024-04-18(0)
2024-04-17(5)

代码天地 © 2018 codetd.com

境外服务器   最新电视剧2022