【RestFul接口文档】- 关于Swagger接口文档的使用说明
文章目录
Swagger
1.Swagger简介
- 号称世界上最流行的API框架
- RESTful 文档自动生成工具 =>API文档和API定义同步进行
- 直接运行可测试API接口
- 支持多种语言（java，。。）
Swagger在项目中的使用需要springbox
- swagger
- ui
2.Springboot集成Swagger
1.新建Springboot项目
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>
3.编写Hello项目
4.开启Swagger支持 =>Config
@Configuration
@EnableSwagger2 //开启Swagger支持
public class SwaggerConfig {
}
5.测试运行http://localhost:8000/swagger-ui.html
3.Swagger的配置
1.注入Swagger的bean
@Configuration
@EnableSwagger2 //开启Swagger支持
public class SwaggerConfig {
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2);
}
}
Swagger中有许多信息都是默认的，我们可以修改
2.修改Swagger的ApiInfo信息
可以看到在Docket中第一个赋值的就是这个属性。
可以通过new出来的Docket对象直接设置
Swagger的ApiInfo的配置
@Configuration
@EnableSwagger2 //开启Swagger支持
public class SwaggerConfig {
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo());
}
//修改Swagger的ApiInfo信息
private ApiInfo apiInfo(){
return new ApiInfo(
"wf的API文档",//标题
"学习Swagger的开发API文档",//APi文档的描述
"v1.0",
"https://blog.csdn.net/gyhdxwang",//开发的组织
new Contact("wf", "https://blog.csdn.net/gyhdxwang", "wangfeng614@163.com"),//开发者信息
"Apache 2.0",//默认开源协议
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList<VendorExtension>());
}
}
3.运行测试
可以看到Swagger已经变成我们修改的内容；
4.Swagger配置扫描接口
可以看到Swagger默认扫描所有的接口。如果我们想让Swagger只扫描特定的端口，可以使用以下方法；
Swagger的接口扫描是通过select来build的。而其扫描有两种方式：
- apis：要扫描哪些路径
- paths：不要扫描哪些路径
Swagger的apis扫描方式
apis的扫描是通过一个叫RequestHandlerSelectors类来进行配置，该类有5种扫描的方式。
-
basePackage
可以看到在配置扫描的包后，其他非该包下的内容就不会被扫描出来
-
any和none：就是全部扫描，和全部不扫描
-
withClassAnnotation:扫描类上注解，注解的类（反射对象）
扫描带有特定注解的类
-
withMethodAnnotation：扫描接口上的注解
扫描带有特定注解的方法
Swagger的apis方式最常用的方式是basePackage的方式
Swagger的paths的不扫描方式
该方式是提高PathSelectors选择器来实现，有4种方式
- ant：过滤特定包下的内容
过滤的结果
- regex：字符匹配
关于Swagger扫描的代码：
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//RequestHandlerSelectors:配置要扫描接口的方法
//basePackage:通过包名来扫描
//any:全部扫描
//none:都不扫描
//withClassAnnotation:扫描类上注解，注解的类（反射对象）
//withMethodAnnotation:扫描接口上的注解
.apis(RequestHandlerSelectors.withMethodAnnotation(GetMapping.class))
//paths:设置过滤的路径
//PathSelectors:配置扫描的方式
.paths(PathSelectors.ant("/wf/**"))
.build()//这是一个工厂模式
;
}
5.配置Swagger是否启动
该功能是通过Docket类的Enabled属性实现
如何在config中配置
- true表示开启
- false表示不开启
当Enabled配置为false时
不能扫描
关于是否开启Swagger的代码
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.enable(false)
.select()
.apis(RequestHandlerSelectors.basePackage("wf.start.swaggerdemo.controller"))
.build()//这是一个工厂模式
;
}
问题如何配置Swagger在生产环境使用，发布时不使用
先配置环境，激活dev，dev端口是8001，pro端口是8002
我们对Docket进行配置
@Bean
public Docket docket(Environment environment){
//获取项目的环境
//1.先在方法添加Environment参数import org.springframework.core.env.Environment;
//2.获取要显示Swagger的环境
//of方法接收一个可变String参数
Profiles profiles = Profiles.of("dev");
//通过environment.acceptsProfiles判断是否在自己设定的环境
boolean flag = environment.acceptsProfiles(profiles);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.enable(flag)
.select()
.apis(RequestHandlerSelectors.basePackage("wf.start.swaggerdemo.controller"))
.build()//这是一个工厂模式
;
}
先参数dev开发环境，
可以访问成功（注意dev环境配置的端口是8001，所以要访问8001的swagger-ui）
对pro环境进行测试
在开发环境下不显示。配置成功
6.配置API文档的分组
注意：此时关闭5中的多个环境，只使用最开始的8000端口（在application.properties中配置）
swagger中的分组是通过
.groupName("wf")
实现的。
例如：
@Bean
public Docket docket(Environment environment){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.groupName("wf")
.select()
.apis(RequestHandlerSelectors.basePackage("wf.start.swaggerdemo.controller"))
.build()//这是一个工厂模式
;
}
运行截图
而分组依赖于Docket实例存在，如果想要配置多个分组,配置多个Swagger的bean即可。
配置多个分组：
@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");
}
运行结果
Swagger的分组配置成功！
7.对文档的具体配置
实体类配置
编写一个配置类
package wf.start.swaggerdemo.entity;
/**
* @Description TODO
* @Author gyhdx
* @Date 2020/6/2 9:04
*/
public class User {
public String userName;
public String password;
public User() {
}
public User(String userName, String password) {
this.userName = userName;
this.password = password;
}
}
如果想要在Swagger的最下面的modle中显示该实体类，只需要在接口中返回该实体类即可
@RestController
public class HelloController {
@GetMapping("/hello")
public String hello(){
return "hello";
}
//只要我们的Controller接口的返回之中存在实体类就会在Swagger的modle中显示
@GetMapping("/userTest")
public User getTest(){
return new User("wf","1234");
}
}
给实体类添加注释
我们上面虽然可以正常显示实体类，但是如果实体类中的参数过多我们可能就不知道，实体类中的具体参数的意思，此时我们需要给实体类添加注释
给实体类添加注解只需要两个参数；
- @ApiModel：用于注解实体类
- @ApiModelProperty：用于给实体类中的参数添加注解
@ApiModel("这是user的实体类")
public class User {
@ApiModelProperty("用户名")
public String userName;
@ApiModelProperty("密码")
public String password;
public User() {
}
public User(String userName, String password) {
this.userName = userName;
this.password = password;
}
}
运行结果
对controller接口添加注解
给controller接口添加注解主要是用来一下两个注解：
- @ApiOperation：这是给接口添加注解
- @ApiParam：给接口中的参数添加注解
- 注意：在给参数添加注解时，如果接口参数是一个实体类，则Swagger会显示实体类的注解，不会显示我们配置的
@RestController
public class HelloController {
@GetMapping("/hello")
public String hello(){
return "hello";
}
//只要我们的Controller接口的返回之中存在实体类就会在Swagger的modle中显示
@GetMapping("/userTest")
public User getTest(){
return new User("wf","1234");
}
@ApiOperation("get测试接口")
@GetMapping("/getTest")
public User getTest2(@ApiParam("这是用户名") String userName){
return new User("wf","1234");
}
@ApiOperation("post测试接口")
@PostMapping("/postt")
public User gett(@ApiParam("用户信息") User user){
return user;
}
}
运行结果：
4.在Swagger-ui中进行接口的测试
在Swagger显示的接口中有一个try it out按钮，该按钮就会开启测试界面，点击该按钮
出现Execute点击
会把返回体和，返回头的内容添加。
对于post请求也一样
不过不知道为什么，我的post测试时它使用get的方式进行测试，而进行get带参数测试时swagger使用post方式请求。不知道哪位大神能解决我的这个问题
5.总结
- 1.可以使用Swagger给一些比较难以理解的接口或属性添加注释
- 2.swagger产生的接口文档会实时更新
- 3.可以在线测试（虽然我的接口测试存在问题）
Swagger是一个优秀的工具，几乎所有大公司都有使用它
[注意点]：在正式发布的时候,关闭Swagger! ! !出于安全考虑。而且节省运行的内存;
