Swagger
作者:互联网
前言
现在很多项目都开始使用前后端分离的架构方式了,前后端分离带来诸多好处的同时,也面临了一些问题,比如前后端开发人员的协同问题。
之前一般是通过文档的形式来定义接口,然后前后端开发人员根据接口去各自开发,但是测试的时候往往会发现有对应不上的情况!
前端添加一个字段,后端则可能修改一系列的方法,这种情况带来了很大的麻烦,因此Swagger应运而生!
目录
Swagger 概念
Swagger 使用场景
Swagger 配置-文档信息
Swagger 配置-接口扫描/过滤
Swagger 配置-分组
Swagger 配置-API注解
使用 Swagger测试接口
Swagger 概念
Swagger主要应用于前后端分离项目的协同开发,通过简单易用的配置,即可实现接口信息文档的实时更新,使得开发更见高效和便捷!
Swagger 使用场景
从开发的角度,这是对于前后端分离而且前后端人员分离的情况的!
如果是前后端分离,但是前后端人员不分离、甚至就是一个人承包了前后端,那实属没必要了~~~
从项目周期的角度,Swagger 在开发和测试时使用,上线则需要关闭。
Swagger 配置
1. 添加依赖包:swagger2、swagger-ui
<!-- 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>
添加配置类,并开启Swagger
package com.hwl.swgger01.config; import org.springframework.context.annotation.Configuration; import springfox.documentation.swagger2.annotations.EnableSwagger2; @Configuration @EnableSwagger2 //并开启Swagger public class SwaggerConfig { }
完成上门两步已经能使用Swagger了,非常简单。
测试访问 http://localhost:8080/swagger-ui.html
Swagger提供的界面有四个信息模块,如上图。
配置Swagger
实际开发中,我们一般不使用默认的配置,而是根据需要进行自定义自己的配置
Swagger的配置主要使用Docket这个实例提供的接口进行配置,从而实轻松现来接管默认配置。
注入配置实例,并修改Swagger信息
package com.hwl.swgger01.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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;
@Configuration
@EnableSwagger2
public class SwaggerConfig {
//配置并注入swagger的Docket实例,接管默认的配置信息
@Bean
public Docket docket(){
return new Docket( DocumentationType.SWAGGER_2 ) //参数 DocumentationType:SWAGGER_12/SWAGGER_2/SPRING_WEB
.apiInfo( setApiInfo() );
}
//配置swagger的apiInfo,参考默认配置修改
private ApiInfo setApiInfo(){
Contact contact = new Contact( "工程师01","hello.com","yunnanhwl@163.com" );//作者信息
return new ApiInfo(
"我的标题你做主",
"swagger有点好用",
"1.0",
"urn:tos",
contact,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList());
}
}
运行查看修改结果:
自定义配置扫描接口
默认的配置是扫描出全部的接口的,例如springBoot默认的错误页面的接口。有时候我们只希望扫描自己想要的接口,这种情况也是通过Docket对象来设置:
//配置并注入swagger的Docket实例,接管默认的配置信息 @Bean public Docket docket(){ return new Docket( DocumentationType.SWAGGER_2 ) //参数 DocumentationType:SWAGGER_12/SWAGGER_2/SPRING_WEB .apiInfo( setApiInfo() ) .select() .apis( RequestHandlerSelectors.basePackage("com.hwl.swgger01.controller") ) //配置扫描包 .build(); }
现在访问只有我们指定包下面的接口了:
通过源码发现这里的扫描策略有以下几种
- any //扫描全部
- none //都不扫描
- withMethodAnnotation //扫描方法上的注
- withClassAnnotation //扫描类上的注解,参数,例子:RestController.calss就只会扫描这样的类输出api
以上我们是通过Docket对象的apis来设置扫描哪些包,但有时候我们需要的包下面有些类或接口又是不需要扫描的,这时候需要使用过滤:
.apis() //配置扫描哪些包 .paths()//配置哪些需要过滤
Swagger的内置开关
Swagger是开发提供了方便,但是一旦产品上线,测需要去掉Swagger,除了直接的代码摘除,其实Swagger提供了接口用来直接关闭:
.enable( flag ) //flag为false则关闭Swagger
一般会根据项目的环境来判断是否开启,当环境为开发、测试环境时开启:
分组协同开发
.groupName("Group01")
各组来实现自己的Docket配置,从而实现各组的实际对外显示情况:
//配置并注入swagger的Docket实例,接管默认的配置信息 @Bean public Docket docket(){ return new Docket( DocumentationType.SWAGGER_2 ) //参数 DocumentationType:SWAGGER_12/SWAGGER_2/SPRING_WEB .apiInfo( setApiInfo() ) .groupName("Group01") .select() .apis( RequestHandlerSelectors.basePackage("com.hwl.swgger01.controller") ) //配置扫描哪些 .build(); } @Bean public Docket docket1(){ return new Docket( DocumentationType.SWAGGER_2 ) .apiInfo( setApiInfo() ) .groupName("Group02"); }
显示如下:
实体类
在前后端分离协同开发中,除了需要沟通接口外,实体类也是很重要的。
使用Swagger后,只要扫描显示的接口中,返回值带有某个实体类,那么该实体类会自动被Swagger加入到module中显示出来:
返回值:
@RequestMapping("/getUser") public User hello(){ return new User( "lihua","123456" ); }
Swagger自动显示相关的实体:
此外,为了Swagger文档的友好性,Swagger还提供了一些注解来对类、方法、字段等进行一个额外的注释说明:
如:
@ApiModel("用户信息") 用来标注解释实体类,访问swagger时讲看到注释信息,提供了一定的友好度。
使用Swagger进行接口测试
swagger还直接提供了接口的测试功能,非常方便!
标签:配置,扫描,接口,import,Swagger,Docket 来源: https://www.cnblogs.com/haola/p/15362814.html