目录
本文适合第一次想亲手编写一个swagger的人看,这篇文章是我第一次学习时的笔记。
swagger官网:https://swagger.io/
1.创建一个springboot项目
file-》new-》project-》spring initializr -》直接下一步选择java8-》选择web ,spring web
2.添加swagger依赖
我pom中引用的是2.4.0版本
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>${swagger.version}</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>${swagger.version}</version>
</dependency>
3.添加swagger配置
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.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
public class swaggerConfig {
//docket具体方法实现,然后加一系列东西,apiinfo自己实现,pathMapping配置访问路径
//PathSelectors.regex("/.*") 正则匹配路径
@Bean
public Docket api(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.pathMapping("/")
.select()
.paths(PathSelectors.regex("/.*"))
.build();
}
private ApiInfo apiInfo(){
//contact联系人
return new ApiInfoBuilder()
.title("我的接口")
.contact(new Contact("wangyi","http://localhost:8868/mike/swagger-ui.html#/user-controller/queryUserInfoUsingPOST","loving9906@163.com"))
.description("swagger的第一次使用")
.version("1.0.0.0")
.license("王一的csdn博客地址")
.licenseUrl("http://localhost:8868/mike/swagger-ui.html#/user-controller/queryUserInfoUsingPOST")
.build();
}
}
配置完就可以尝试启动程序了,访问localhost:8080出现如下界面
4.增添swagger界面中方法的调用
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestHeader;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.context.request.RequestContextHolder;
import org.springframework.web.context.request.ServletRequestAttributes;
import javax.servlet.http.HttpServletRequest;
@RestController
@RequestMapping(value = "/user")
public class MyMetheod {
@GetMapping(value = "/get-token")
@ApiOperation(value = "获取请求头中的token信息")
public void getToken(
@RequestHeader(value = "token",required = false) 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);
}
}
}
再次执行就有如下界面
5.swagger-ApiImplicitParams注释的使用
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
/**
* 加参数测试
*/
@RequestMapping(value = "/param")
@RestController
public class AddParam {
@GetMapping(value = "/")
@ApiOperation(value = "测试我的参数程序")
@ApiImplicitParams({
@ApiImplicitParam(name = "startTime", value = "起始时间", dataType = "string", paramType = "query", required = false),
@ApiImplicitParam(name = "endTime", value = "结束时间", dataType = "string", paramType = "query", required = false)
})
@ApiResponses({
@ApiResponse(code = 100, message = "异常数据")
})
public void paratest(@RequestParam(required = false) String startTime,
@RequestParam(required = false) String endTime){
System.out.println("开始时间:"+startTime);
System.out.println("结束时间:"+endTime);
}
}
控制台输出的结果
6.消除basic-error-controller : Basic Error Controller
.paths(Predicates.not(PathSelectors.regex("/error.*")))//错误路径不监控
效果图
补充
application.yml文件可以修改端口号和访问时候的路径,默认端口是8080
swagger常用注释
@Api():用在请求的类上,表示对类的说明,也代表了这个类是swagger2的资源
参数:
tags:说明该类的作用,参数是个数组,可以填多个。
value="该参数没什么意义,在UI界面上不显示,所以不用配置"
description = "用户基本信息操作"
@ApiOperation():用于方法,表示一个http请求访问该方法的操作
参数:
value="方法的用途和作用"
notes="方法的注意事项和备注"
tags:说明该方法的作用,参数是个数组,可以填多个。
格式:tags={"作用1","作用2"}
(在这里建议不使用这个参数,会使界面看上去有点乱,前两个常用)
@ApiModel():用于响应实体类上,用于说明实体作用
@ApiModelProperty:用在属性上,描述实体类的属性
@ApiImplicitParams:用在请求的方法上,包含多@ApiImplicitParam 用于方法,表示单独的请求参数
参数:
name="参数ming"
value="参数说明"
dataType="数据类型"
paramType="query" 表示参数放在哪里
· header 请求参数的获取:@RequestHeader
· query 请求参数的获取:@RequestParam
· path(用于restful接口) 请求参数的获取:@PathVariable
· body(不常用)
· form(不常用)
defaultValue="参数的默认值"
required="true" 表示参数是否必须传
@ApiParam():用于方法,参数,字段说明 表示对参数的要求和说明
@ApiResponses:用于请求的方法上,根据响应码表示不同响应
@ApiResponse:用在请求的方法上,表示不同的响应
@ApiIgnore():用于类或者方法上,不被显示在页面上
@Profile({“dev”, “test”}):用于配置类上,表示只对开发和测试环境有用