Swagger使用详解
目录
一、简介
二、SwaggerTest项目搭建
1. pom.xml
2. entity类
3. controller层
三、基本使用
1. 导入相关依赖
2. 编写配置文件
2.1 配置基本信息
2.2 配置接口信息
2.3 配置分组信息
2.3.1 分组名修改
2.3.2 设置多个分组
四、常用注解使用
1. @ApiModel
2.@ApiModelProperty
3.@ApiOperation
4. @ApiParam
五、Swagger接口调用
六、添加请求头
一、简介
前言
Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步
Why Swagger？
当下很多公司都采取前后端分离的开发模式，前端和后端的工作由不同的工程师完成，在这种开发模式下，维持一份及时更新且完整的 Rest API 文档将会极大的提高我们的工作效率。传统意义上的文档都是后端开发人员手动编写的，这种方式很难保证文档的及时性，这种文档久而久之也就会失去其参考意义，反而还会加大我们的沟通成本。而 swagger 给我们提供了一个全新的维护 API 文档的方式
作为后端开放人员，最烦的事就是自己写接口文档和别人没有写接口文档，不管是前端还是后端开发，多多少少都会被接口文档所折磨，前端会抱怨后端没有及时更新接口文档，而后端又会觉得编写接口文档太过麻烦。Swagger 可以较好的接口接口文档的交互问题，以一套标准的规范定义接口以及相关的信息，就能做到生成各种格式的接口文档，生成多种语言和客户端和服务端的代码，以及在线接口调试页面等等。只需要更新 Swagger 描述文件，就能自动生成接口文档，做到前端、后端联调接口文档的及时性和便利性
作用
1.支持 API 自动生成同步的在线文档：使用 Swagger 后可以直接通过代码生成文档，不再需要自己手动编写接口文档了，对程序员来说非常方便
2.提供 Web 页面在线测试 API：Swagger 生成的文档支持在线测试。参数和格式都定好了，直接在界面上输入参数对应的值即可在线测试接口
二、SwaggerTest项目搭建
1. pom.xml
4.0.0
com.swagger
SwaggerTest
1.0-SNAPSHOT
8
8
org.springframework.boot
spring-boot-starter
2.2.6.RELEASE
org.springframework.boot
spring-boot-starter-web
2.2.6.RELEASE
org.projectlombok
lombok
1.18.24
io.springfox
springfox-spring-web
2.9.2
io.springfox
springfox-swagger2
2.9.2
io.springfox
springfox-swagger-ui
2.9.2
2. entity类
package com.swagger.entity;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
@Data
@AllArgsConstructor
@NoArgsConstructor
public class User {
private Long id;
private String name;
private int age;
}
3. controller层
package com.swagger.controller;
import com.swagger.entity.User;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.*;
@RestController
@RequestMapping("/user")
public class UserController {
@GetMapping("/getByName")
public String getByName(){
return "访问getByName成功";
}
@PostMapping("/login")
public String login(@RequestBody User user){
return "登录成功";
}
}
三、基本使用
1. 导入相关依赖
io.springfox
springfox-spring-web
2.9.2
io.springfox
springfox-swagger2
2.9.2
io.springfox
springfox-swagger-ui
2.9.2
2. 编写配置文件
@Configuration // 配置类
@EnableSwagger2 // 开启 swagger2 的自动配置
public class SwaggerConfig {
}
这个时候 Swagger 已经算是整合到项目之中了，可以启动下服务，输入：http://localhost:8080/swagger-ui.html# 即可查看Swagger文档，可以看到如下信息
- 组
- 基本信息
- 接口信息
- 实体类信息
2.1 配置基本信息
Swagger 在自己的实例Docket中可以设置自定义基本信息于ApiInfo对象中，下图为Swagger默认的基本信息
ApiInfo中默认的基本信息
- title:Api Documentation
- description:Api Documentation
- version:1.0
- termsOfServiceUrl:urn:tos
- contact:无
- license：Apache 2.0
- licenseUrl:http://www.apache.org/licenses/LICENSE-2.0
这些信息都不是我们需求的，我们可以在Swagger配置文件中去配置属于我们自己项目的接口文档信息，代码如下
package com.swagger.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
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;
@Configuration // 配置类
@EnableSwagger2 // 开启 swagger2 的自动配置
public class SwaggerConfig {
@Bean
public Docket docket() {
// 创建一个 swagger 的 bean 实例
return new Docket(DocumentationType.SWAGGER_2)
// 配置基本信息
.apiInfo(apiInfo());
}
// 基本信息设置
private ApiInfo apiInfo() {
Contact contact = new Contact(
"Keke", // 作者姓名
"https://blog.csdn.net/m0_63732435?spm=1011.2124.3001.5343", // 作者网址
"[email protected]"); // 作者邮箱
return new ApiInfoBuilder()
.title("SwaggerTest-接口文档") // 标题
.description("这是关于Swagger学习测试的接口文档") // 描述
.termsOfServiceUrl("https://www.baidu.com") // 跳转连接
.version("1.0") // 版本
.license("Swagger-的使用(详细教程)")
.licenseUrl("https://blog.csdn.net/m0_63732435/article/details/133689227?spm=1001.2014.3001.5501")
.contact(contact)
.build();
}
}
重新启动服务，效果如下
2.2 配置接口信息
默认情况下，Swagger是会展示所有的接口信息的，包括最基础的basic-error相关接口
有时候我们希望不要展示 basic-error-controller 相关的接口，或者有其他需求，可以看以下代码和注释理解运用
@Bean
public Docket docket() {
// 创建一个 swagger 的 bean 实例
return new Docket(DocumentationType.SWAGGER_2)
//配置基本信息
.apiInfo(apiInfo())
// 配置接口信息
.select() // 设置扫描接口
// 配置如何扫描接口
.apis(RequestHandlerSelectors
//.any() // 扫描全部的接口，默认
//.none() // 全部不扫描
.basePackage("com.swagger.controller") // 扫描指定包下的接口，最为常用
//.withClassAnnotation(RestController.class) // 扫描带有指定注解的类下所有接口
//.withMethodAnnotation(PostMapping.class) // 扫描带有只当注解的方法接口
)
.paths(PathSelectors
.any() // 满足条件的路径，该断言总为true
//.none() // 不满足条件的路径，该断言总为false（可用于生成环境屏蔽 swagger）
//.ant("/user/**") // 满足字符串表达式路径
//.regex("") // 符合正则的路径
)
.build();
}可以看到，basic-error相关接口我们已经去除了
2.3 配置分组信息
Swagger默认只有一个分组，名为default，如果不设置，所有的接口都会在这个分组下。在多模块项目下，我们通常会需要建立多个分组来分类管理这些接口，来防止接口混杂在一起
2.3.1 分组名修改
@Bean
public Docket docket() {
// 创建一个 swagger 的 bean 实例
return new Docket(DocumentationType.SWAGGER_2)
//设置分组名
.groupName("admin")
}可以看到分组名修改为admin
2.3.2 设置多个分组
实际上创建几个Docket对象，就有几个分组，代码如下
package com.swagger.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
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;
@Configuration // 配置类
@EnableSwagger2 // 开启 swagger2 的自动配置
public class SwaggerConfig {
@Bean
public Docket docket() {
// 创建一个 swagger 的 bean 实例
return new Docket(DocumentationType.SWAGGER_2)
//设置分组名
.groupName("admin")
//配置基本信息
.apiInfo(apiInfo())
// 配置接口信息
.select() // 设置扫描接口
// 配置如何扫描接口
.apis(RequestHandlerSelectors
//.any() // 扫描全部的接口，默认
//.none() // 全部不扫描
.basePackage("com.swagger.controller") // 扫描指定包下的接口，最为常用
//.withClassAnnotation(RestController.class) // 扫描带有指定注解的类下所有接口
//.withMethodAnnotation(PostMapping.class) // 扫描带有只当注解的方法接口
)
.paths(PathSelectors
.any() // 满足条件的路径，该断言总为true
//.none() // 不满足条件的路径，该断言总为false（可用于生成环境屏蔽 swagger）
//.ant("/user/**") // 满足字符串表达式路径
//.regex("") // 符合正则的路径
)
.build();
}
@Bean
public Docket docket1() {
// 创建一个 swagger 的 bean 实例
return new Docket(DocumentationType.SWAGGER_2)
//设置分组名
.groupName("blog")
//配置基本信息
.apiInfo(apiInfo())
// 配置接口信息
.select() // 设置扫描接口
// 配置如何扫描接口
.apis(RequestHandlerSelectors
//.any() // 扫描全部的接口，默认
//.none() // 全部不扫描
.basePackage("com.swagger.controller") // 扫描指定包下的接口，最为常用
//.withClassAnnotation(RestController.class) // 扫描带有指定注解的类下所有接口
//.withMethodAnnotation(PostMapping.class) // 扫描带有只当注解的方法接口
)
.paths(PathSelectors
.any() // 满足条件的路径，该断言总为true
//.none() // 不满足条件的路径，该断言总为false（可用于生成环境屏蔽 swagger）
//.ant("/user/**") // 满足字符串表达式路径
//.regex("") // 符合正则的路径
)
.build();
}
// 基本信息设置
private ApiInfo apiInfo() {
Contact contact = new Contact(
"Keke", // 作者姓名
"https://blog.csdn.net/m0_63732435?spm=1011.2124.3001.5343", // 作者网址
"[email protected]"); // 作者邮箱
return new ApiInfoBuilder()
.title("SwaggerTest-接口文档") // 标题
.description("这是关于Swagger学习测试的接口文档") // 描述
.termsOfServiceUrl("https://www.baidu.com") // 跳转连接
.version("1.0") // 版本
.license("Swagger-的使用(详细教程)")
.licenseUrl("https://blog.csdn.net/m0_63732435/article/details/133689227?spm=1001.2014.3001.5501")
.contact(contact)
.build();
}
}
可以看到blog模块分组的接口文档也在UI界面中展示出来
四、常用注解使用
1. @ApiModel
该注解是作用在类上的，用来描述类的一些基本信息的
相关属性：
- value：提供类的一个备用名，如果不设置，默认情况下将使用 class 类的名称
- description：对于类，提供一个详细的描述信息
- parent：这个属性用于描述的是类的一些父类信息
- discriminator：这个属性解释起来比较麻烦，因为这个类主要体现在断言当中
- subTypes：可以通过这个属性，指定我们想要使用的子类
2.@ApiModelProperty
添加和操作属性模块的数据
package com.swagger.entity;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel(value = "user实体类")
public class User {
@ApiModelProperty(value = "id主键")
private Long id;
@ApiModelProperty(value = "用户姓名")
private String name;
@ApiModelProperty(value = "用户年龄")
private int age;
}
可以看到Model展示出来一些描述信息
3.@ApiOperation
该注解用来对某个方法/接口进行描述
@GetMapping("/getByName")
@ApiOperation(value = "根据姓名查询用户")
public String getByName(){
return "访问getByName成功";
}可以看到接口文档这里多了 根据姓名查询用户 的描述
4. @ApiParam
该注解使用在方法上或者参数上，字段说明，表示对参数的添加元数据（说明或者是否必填等）
相关属性：
- name：参数名
- value：参数说明
- required：是否必填
@GetMapping("/getByName/{id}")
@ApiOperation(value = "根据id查询用户")
public String getById(@ApiParam(value = "用户id",required = true) @PathVariable Long id){
return "访问getById成功";
}可以看到，添加@ApiParam注解后，接口文档多了对参数的相应描述说明
五、Swagger接口调用
swagger 除了让前后端交互变得方便，在swagger中也可以发起请求测试接口，只需要填写好请求所需要的参数信息即可
点击Excute就可以看到接口响应的结果了
六、添加请求头
在登录注册类似涉及安全验证的业务，例如SpringSecurity框架中我们的接口是需要获取请求头信息的，这样的话就还需要在 swagger 配置中添加请求头的配置。
@Bean
public Docket docket() {
// 设置请求头
List parameters = new ArrayList<>();
parameters.add(new ParameterBuilder()
.name("token") // 字段名
.description("token") // 描述
.modelRef(new ModelRef("string")) // 数据类型
.parameterType("header") // 参数类型
.defaultValue("default value") // 默认值：可自己设置
.hidden(true) // 是否隐藏
.required(false) // 是否必须
.build());
// 创建一个 swagger 的 bean 实例
return new Docket(DocumentationType.SWAGGER_2)
.groupName("mike") // 修改组名为 "mike"
// 配置接口信息
.select() // 设置扫描接口
// 配置如何扫描接口
.apis(RequestHandlerSelectors
.basePackage("com.duojiala.mikeboot.controller") // 扫描指定包下的接口，最为常用
)
.paths(PathSelectors
.any() // 满足条件的路径，该断言总为true
)
.build()
// 添加请求头参数
.globalOperationParameters(parameters);
}
接口
@GetMapping(value = "/getToken")
@ApiOperation(value = "获取请求头中的token信息")
public void getToken(
@RequestHeader(value = "token",required = true) String token
) {
// 直接获取 token 信息
System.out.println("token = " + token);
// 通过代码获取
ServletRequestAttributes servletRequestAttributes = (ServletRequestAttributes) RequestContextHolder.getRequestAttributes();
if (servletRequestAttributes != null) {
HttpServletRequest request = servletRequestAttributes.getRequest();
String header = request.getHeader("token");
System.err.println("header = " + header);
}
}
这样重启服务，接口就可以设置请求头了
执行后，后端控制台可以打印http请求带来的token的信息