目录
一、什么是swagger
二、如何使用swagger
最近我在写crud,想起之前开发他们在用swagger做接口管理,我就想试试,然后就把JavaWeb项目如何接入swagger的过程记录下来。
一、什么是swagger
swagger是一个API文档工具。是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务的接口文档。
总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法、参数和模型紧密集成到服务器端的代码,允许 API 来始终保持同步。
swagger官网:https://swagger.io/。
二、如何使用swagger
1、添加springfox-swagger2 pom依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
2、添加SwaggerConfig.java
@Configuration
@EnableSwagger2
public class SwaggerConfig {
//作为Springfox框架的主要接口的构建器,提供合理的默认值和方便的配置方法。@Bean
public Docket docket() {
ParameterBuilder builder = new ParameterBuilder();
builder.parameterType("header").name("token")
.description("token值")
.required(false) //设置为true则必须要传token
.modelRef(new ModelRef("string")); //在swagger里显示header
return new Docket(DocumentationType.SWAGGER_2)
.groupName("java_web")
.apiInfo(apiInfo())
.globalOperationParameters(Lists.newArrayList(builder.build()))
.select().paths(PathSelectors.any()).build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Learn-Java系统") //标题
.description("学习Java-Web接口文档") //描述
.contact(new Contact("wmh", "", "1425615649@qq.com")) //联系人
.version("1.0") //版本号
.build();
}
}
3、在controller层添加swagger配置
@Api(tags = "Swagger测试用户管理模块", description = "我是一个描述", hidden = true)
@RestController
@RequestMapping("/api/user")
public class SwaggerTestUserController {
/**
* 查询用户列表,返回一个JSON数组
*/
@ApiOperation("查询用户列表")
@GetMapping("/users")
@ResponseStatus(HttpStatus.OK)
public Object getUsers() {
List<UserDto> list = getData();
return list;
}
}
4、查看swagger接口列表
启动项目后在浏览器进行访问:
http://127.0.0.1:9999/swagger-ui.html#/,即可查询controller层所有接口。
可以直接在上面测试接口,不需要去打开JMeter或者postman,直接在页面操作就行,非常方便!
而且重启项目即可更新接口,可以理解为接口文档和代码实时同步!
注意如果不需要鉴权的话,在SwaggerConfig.java需要设置为false。
相关代码在https://gitee.com/weimenghua/Learn-Java,双击bin/start.bat即可运行项目,
访问地址:http://127.0.0.1:9999/swagger-ui.html#/。
https://www.processon.com/view/link/615eae81e0b34d06f3dcdf4b