前言
项目组中使用了 SpringBoot + Swagger UI 来生成 Restful API 文档和测试页面。
本文来体验一下 Swagger UI 的用法。
简介
Swagger UI 是目前最流行的 RestFul 接口 API 文档和测试工具,可以直接在官方 demo 上进行体验。
本文介绍下如何在 SpringBoot2 中集成 Swagger UI。
初体验
非常简单,只需要两步即可。
依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
第二个依赖中包含有前端 js/css 资源。
编写配置文件
package com.example.testredisreactive;
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
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("后端接口标题")
.description("后端接口描述")
.contact(
new Contact("flowaters", "note.abeffect.com", "flowaters@abeffect.com")
)
.version("1.0.0-SNAPSHOT")
.build();
}
}
使用
打开浏览器,访问 http://localhost:8080/swagger-ui.html
即可
api 选择器
如何只筛选出指定的 API 呢?
包名
一种方法是,根据包名来筛选
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.example"))
.paths(PathSelectors.any())
.build();
}
path
另一种方法是,根据 path 来筛选
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.example"))
.paths(PathSelectors.ant("/get"))
.build();
}
当然也可以两者配合来筛选。
详细文档
怎么样生成详细的文档呢?
通过在接口类上增加对应的注解,如下面的示例。
- 在类上增加
Api
注解 - 在方法上增加
ApiOperation
注解 - 在参数上增加
ApiParam
注解 - 在模型字段上
ApiModelProperty
增加注解
具体如下:
package com.example.testredisreactive;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.data.redis.core.RedisTemplate;
import org.springframework.data.redis.core.StringRedisTemplate;
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;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
@RestController
@RequestMapping("/api/1.0/kv")
@Api(description = "KV存储相关接口的描述", tags = "KV存储相关接口的TAG")
public class TestController {
private static final Logger logger = LoggerFactory.getLogger(TestController.class);
@Autowired
RedisTemplate redisTemplate;
@Autowired
StringRedisTemplate stringRedisTemplate;
@GetMapping(value = "/set")
@ApiOperation(notes = "使用默认的序列化方法", value = "设置KV对")
public void set(@ApiParam(required = true, value = "key") String key,
@ApiParam(required = true, value = "value") String value) {
stringRedisTemplate.opsForValue().set(key, value);
}
@GetMapping(value = "/get")
@ApiOperation(value = "查询KV对")
public String get(@ApiParam(required = true, value = "KV对中的key, 字符串类型")
@RequestParam(defaultValue = "key", required = false) String key) {
return stringRedisTemplate.opsForValue().get(key);
}
@GetMapping(value = "/getdo")
public KVDO getDo(String key) {
String value = stringRedisTemplate.opsForValue().get(key);
return new KVDO(key, value);
}
}
数据模型示例
package com.example.testredisreactive;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
@Data
@AllArgsConstructor
public class KVDO {
@ApiModelProperty(required = true, value = "KVDO中的键")
private String key;
@ApiModelProperty(required = true, value = "KVDO中的值")
private String value;
}
欢迎来到这里!
我们正在构建一个小众社区,大家在这里相互信任,以平等 • 自由 • 奔放的价值观进行分享交流。最终,希望大家能够找到与自己志同道合的伙伴,共同成长。
注册 关于