1、Swagger
Swagger 是一个规范且完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务
Swagger 的目标是对 REST API 定义一个标准且和语言无关的接口,可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过 Swagger 进行正确定义,用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似,Swagger 消除了调用服务时可能会有的猜测
swagger官网地址:https://swagger.io/
1.1、Swagger 的优势
- 支持 API 自动生成同步的在线文档:使用 Swagger 后可以直接通过代码生成文档,不再需要自己手动编写接口文档了,对程序员来说非常方便,可以节约写文档的时间去学习新技术
- 提供 Web 页面在线测试 API:光有文档还不够,Swagger 生成的文档还支持在线测试。参数和格式都定好了,直接在界面上输入参数对应的值即可在线测试接口
1.2、在SpringBoot中集成Swagger
实现步骤:
-
创建一个SpringBoot的Web项目
[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-qfGdVZ4t-1684416211969)(SpringBoot.assets\image-20220401101556577-16487793582701.png)]
-
导入相关依赖 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>
-
编写Controller 测试项目是否创建成功
package com.gjy.controller; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; @RestController public class HelloController { @RequestMapping("/hello") public String hello(){ return "Hello Swagger"; } }
-
配置Swagger==》SwaggerConfig
package com.gjy.config; import org.springframework.context.annotation.Configuration; import springfox.documentation.swagger2.annotations.EnableSwagger2; @Configuration @EnableSwagger2 //开启Swagger2 public class SwaggerConfig { }
-
运行测试 输入http://localhost:8080/swagger-ui.html
[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-AydAspDh-1684416211970)(SpringBoot.assets\image-20220401104624206-16487811860122.png)]
1.3、Swagger配置
完整配置代码:
package com.gjy.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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 //开启Swagger2
public class SwaggerConfig {
//配置Swagger的bean实例
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
}
//配置Swagger信息 apiInfo
private ApiInfo apiInfo() {
//作者信息
Contact contact = new Contact("gjy", "www.gjyblogs.com", "1228981@qq.com");
return new ApiInfo(
"我的Swagger API文档",
"Java是世界上最好的编程语言",
"v1.0",
"www.gjyblogs.com",
contact,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList()
);
}
}
测试结果如下图
[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-lfb8oLY1-1684416211971)(SpringBoot.assets\image-20220401110725329-16487824469373.png)]
1.4、Swagger配置扫描接口
代码实现:
package com.gjy.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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;
@Configuration
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {
//配置Swagger的bean实例
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//RequestHandlerSelectors配置扫描接口的方式
//basePackage指定要扫描的包
//any()扫描全部
//none()不扫描
//withClassAnnotation():扫描类上的注解 参数是一个注解的反射对象
//withMethodAnnotation():扫描方法上的注解
.apis(RequestHandlerSelectors.basePackage("com.gjy.controller"))
//paths() 过滤路径
.paths(PathSelectors.ant("/gjy/**"))
.build()
;
}
//配置Swagger信息 apiInfo
private ApiInfo apiInfo() {
//作者信息
Contact contact = new Contact("gjy", "www.gjyblogs.com", "1228981@qq.com");
return new ApiInfo(
"我的Swagger API文档",
"Java是世界上最好的编程语言",
"v1.0",
"www.gjyblogs.com",
contact,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList()
);
}
}
配置是否启动Swagger
//配置Swagger的bean实例
//enable()是否启动swagger 如果为false,则swagger不能在浏览器中使用
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.enable(true)
;
}
1.5、Swagger面试题
如果只希望Swagger在生产环境的时候使用,在发布的时候不使用 ?
- 判断是否为生产环境
- 注入enable()
代码实现:
package com.gjy.config;
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;
@Configuration
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {
//配置Swagger的bean实例
//enable()是否启动swagger 如果为false,则swagger不能在浏览器中使用
@Bean
public Docket docket(Environment environment) {
//设置要显示的Swagger环境
Profiles profiles = Profiles.of("dev", "pro");
//通过environment.acceptsProfiles()方法判断是否处于特定的环境中
boolean flag = environment.acceptsProfiles(profiles);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.enable(flag)
.select()
//RequestHandlerSelectors配置扫描接口的方式
//basePackage指定要扫描的包
//any()扫描全部
//none()不扫描
//withClassAnnotation():扫描类上的注解 参数是一个注解的反射对象
//withMethodAnnotation():扫描方法上的注解
.apis(RequestHandlerSelectors.basePackage("com.gjy.controller"))
//paths() 过滤路径
.paths(PathSelectors.ant("/gjy/**"))
.build()
;
}
//配置Swagger信息 apiInfo
private ApiInfo apiInfo() {
//作者信息
Contact contact = new Contact("gjy", "www.gjyblogs.com", "1228981@qq.com");
return new ApiInfo(
"我的Swagger API文档",
"Java是世界上最好的编程语言",
"v1.0",
"www.gjyblogs.com",
contact,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList()
);
}
}
1.6、Swagger分组和接口注释
1、配置API文档的分组
.groupName("gjy")
如何配置多个API文档分组 ? 配置多个Docket即可
//配置多个分组
@Bean
public Docket docket1(){
return new Docket(DocumentationType.SWAGGER_2).groupName("A");
}
@Bean
public Docket docket2(){
return new Docket(DocumentationType.SWAGGER_2).groupName("B");
}
@Bean
public Docket docket3(){
return new Docket(DocumentationType.SWAGGER_2).groupName("C");
}
[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-9YkOAhAR-1684416211971)(SpringBoot.assets\image-20220401213515440-16488201172511.png)]
2、实体类配置
代码实现:
package com.gjy.pojo;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
@ApiModel("用户实体类") //对实体类的描述
public class User {
@ApiModelProperty("用户名") //对属性的描述
private String username;
@ApiModelProperty("密码")
private String password;
public String getUsername() {
return username;
}
public void setUsername(String username) {
this.username = username;
}
public String getPassword() {
return password;
}
public void setPassword(String password) {
this.password = password;
}
}
[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-lz0X7EgY-1684416211972)(SpringBoot.assets\image-20220401222207057-16488229288072.png)]
3、接口注释
package com.gjy.controller;
import com.gjy.pojo.User;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class HelloController {
@GetMapping("/hello")
public String hello() {
return "Hello Swagger";
}
//只要接口中,存在返回值为实体类的,它就会被扫描到Swagger的Model中
@PostMapping("/user")
public User user() {
return new User();
}
@ApiOperation("hello接口") //对该接口的描述
@PostMapping("/hello")
public String hello(@ApiParam("用户名") String username) { //对接口参数的描述
return "hello" + username;
}
}
[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-8r1MClVA-1684416211973)(SpringBoot.assets\image-20220401222355513-16488230372083.png)]
总结:
- 我们可以通过Swagger给一些比较难理解的属性或者接口,增加注释信息
- 接口文档实时更新
- 可以在线测试