SpringBoot集成Swagger快速上手

最新推荐文章于 2024-06-13 20:37:51 发布

代码魔法师Sunny

最新推荐文章于 2024-06-13 20:37:51 发布

阅读量420

点赞数

本文链接：https://blog.csdn.net/Hi_alan/article/details/105838556

版权

什么是Swagger

再谈Swagger之前我们先来了解下经常谈到的前后端分离技术

前后端分离：

前端–>前端的控制层，视图层。（专业的前端团队开发）
后端–>后端控制层、服务层、数据访问层（专业的后端团队开发）
前后端的交互是通过API来进行的，关于API的约定该怎么处理呢？

早期：后端编写文档（协同文档），前端根据文档解析接口然后渲染视图！
问题：前后端集成，前端或者后端无法做到：及时协商！最终可能导致问题集中爆发或者项目延时！
所以Swagger就出现了。

什么是Swagger?

号称世界上最流行的API框架
Restful api自动生成文档，和代码对应的
直接运行测试接口，不用下载postman
支持多种语言：（Java，PHP等）
官网：https://swagger.io/

集成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>

编写配置

@Configuration
public class SwaggerConfig {
	// 注册bean Docket
	@Bean
	public Docket docket(){
		return new Docket(DocumentationType.SWAGGER_2);
	}
} 
// 主启动类开启配置！
@SpringBootApplication
// 使Swagger生效，默认是不开启！@EnableSwagger2
@EnableSwagger2
public class SpringbootPlusApplication {
	public static void main(String[] args) {
		SpringApplication.run(SpringbootPlusApplication.class, args);
	}
}

启动测试：
swagger-ui的默认访问地址是当前项目下的swagger-ui.html页面

我们访问地址测试下：http://localhost:8080/swagger-ui.html
编写Controller

@RestController
public class HelloController{

	@RequestMapping("/hello")
	public String hello(){
		return "hello"
	}
}

访问

注意：写Controller的之后一定要精确到方法！

所以要么使用@GetMapping这中形式，要么使用@RequestMapping(value="/hello",method=RequestMethod.GET)

配置Swagger
主要是配置两个核心对象Docket和ApiInfo。
1.构建Docket对象
Docket对象指代的就是我们这个文档Document，他的一些主要配置如下：
在这里插入图片描述

参数名称	参数描述
apiInfo	文档的一些描述信息，包括文档的标题，作者，遵循的开源协议等等
group	组名称，当我们的api接口太多的时候，我们就可以按照功能划分成不同的组
enabled	是否开启，默认是不开启的
genericsNamingStrategy	默认类型名称策略
applyDefaultResponseMessages	是否返回默认的结果信息
host	api文档地址
pathMapping	路径映射
apiSelector	api选择器，可以选择让哪些api显示
enableUrlTemplating	开启urlTemplate模板
vendorExtensions	扩展属性
documentationType	文档类型

@Bean
 public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2) //文档类型
                        .apiInfo(apiInfo()); // 配置文档信息！
 }

配置文档信息 apiInfo
主要参数配置如下：

参数名称	参数描述
title	文档的标题
description	文档的描述信息
version	文档的版本号
termsOfServiceUrl	设置文档的License信息地址
contact	联系人
license	遵循的协议
licenseUrl	协议地址

private ApiInfo apiInfo(){
       Contact contact = new Contact("coding","https://www.xza.com","shiqi2126@gmail.com");//联系方式
       return new ApiInfo(
               "SpringBoot-Plus 接口文档信息",
               "所有的测试请求地址",
               "v1.0", //版本号
               "https://www.xza.com/", //组织连接
               contact,
               "Apache 2.0", //采用的协议
               "http://www.apache.org/licenses/LICENSE-2.0",
               new ArrayList<>());
}

配置接口扫描，需要哪些被扫描到文档中

@Bean
public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
               		   .apiInfo(apiInfo())
                        .select()
                        .apis(RequestHandlerSelectors.basePackage("com.coding.controller"))
                        .build();
}

在这里插入图片描述
常用方法说明：

any() #扫描所有，项目的所有接口都会被扫描的
none() #不扫描接口
basePackage() #根据包路径扫描
withMethodAnnotation(GetMapping.class) #通过方法注解扫描！比如GetMapper.class
withClassAnnotation(Controller.class) #通过类上的注解扫描

设置哪些接口不被扫描

@Bean
public Docket docket(){
        return
                new Docket(DocumentationType.SWAGGER_2)
                        .apiInfo(apiInfo()) // 配置文档信息！
                        .select()
                        .apis(RequestHandlerSelectors.basePackage("com.coding.controller"))
						// 配置path过滤请求！只扫描以 /shiqi 开头的请求！
                        .paths(PathSelectors.ant("/shiqi/**"))
                        .build();
}

在这里插入图片描述

配置Swagger的开关

test、dev环境下才可以显示swagger-ui,prod不显示

@Bean
public Docket docket(){
       return
              new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .enable(false) // 如果是false就无法在浏览器中访问！
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.coding.controller")) //扫描哪个包下的接口
                    .paths(PathSelectors.ant("/kuang/**")) //配置请求路径
                    .build();
}

在这里插入图片描述
这里的false应该是一个变量：技巧点！通过Profiles类来获取限定咱们的开发环境!

@Bean
public Docket docket(Environment environment){
       // 设置要显示的swagger环境
       Profiles of = Profiles.of("dev", "test");
       // 判断是否处于该环境！
       boolean b = environment.acceptsProfiles(of);
       return
             new Docket(DocumentationType.SWAGGER_2)
                   .apiInfo(apiInfo()) // 配置文档信息！
                   .enable(b) // 如果是false就无法在浏览器中访问！
                   .select()
                   .apis(RequestHandlerSelectors.basePackage("com.coding.controller"))
                   .paths(PathSelectors.ant("/kuang/**"))
                   .build();
}

配置API分组
在这里插入图片描述

@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识别
@ApiModel("用户实体")
public class User {
     @ApiModelProperty("用户名")
     private String username;
     @ApiModelProperty("密码")
     private String password;
}

请求的接口配置！如果能够看到实体类配置！如果这个实体类在请求的返回值或者泛型中，那么就会被映射！

// 只有返回值用到才会显示
@GetMapping("/getUser")
public User getUser(){
	return new User();
}

在这里插入图片描述
接口上的配置

@Api(tags="AAAAA测试")
@RestController
public class HelloController {
	@ApiOperation("coding的接口")
	@PostMapping("/coding")
	public String coding(@ApiParam("这个名字会被返回！") String username){
		return username;
	} 
	@GetMapping("/kuang/hello")
	public String hello(){
		return "hello,Swagger";
	} 
	// 只有返回值用到才会显示
	@GetMapping("/getUser")
	public User getUser(){
		return new User();
	}
}

扩展：皮肤包

1、默认的 http://localhost:8081/swagger-ui.html

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

在这里插入图片描述
2、BootStrap-ui http://localhost:8080/doc.html

<!-- https://mvnrepository.com/artifact/com.github.xiaoymin/swagger-bootstrap-ui-->
<dependency>
      <groupId>com.github.xiaoymin</groupId>
      <artifactId>swagger-bootstrap-ui</artifactId>
      <version>1.9.6</version>
</dependency>

在这里插入图片描述
3、Layui的框架 http://localhost:8080/docs.html

<!-- https://mvnrepository.com/artifact/com.github.caspar-chen/swagger-ui-layer -->
<dependency>
     <groupId>com.github.caspar-chen</groupId>
     <artifactId>swagger-ui-layer</artifactId>
     <version>1.1.3</version>
</dependency>

在这里插入图片描述
4、mg-ui http://localhost:8080/document.html

<dependency>
    <groupId>com.zyplayer</groupId>
    <artifactId>swagger-mg-ui</artifactId>
    <version>1.0.6</version>
</dependency>

在这里插入图片描述

代码魔法师Sunny

关注

0
点赞
踩
0

收藏

觉得还不错? 一键收藏
0
评论
SpringBoot集成Swagger快速上手

什么是Swagger再谈Swagger之前我们先来了解下经常谈到的前后端分离技术前后端分离：前端–>前端的控制层，视图层。（专业的前端团队开发）后端–>后端控制层、服务层、数据访问层（专业的后端团队开发）前后端的交互是通过API来进行的，关于API的约定该怎么处理呢？早期：后端编写文档（协同文档），前端根据文档解析接口然后渲染视图！问题：前后端集成，前端或者后端无法...
复制链接

扫一扫