学习Spring Boot:(六) 集成Swagger2
前言
Swagger是用来描述和文档化RESTful API的一个项目。Swagger Spec是一套规范,定义了该如何去描述一个RESTful API。类似的项目还有RAML、API Blueprint。 根据Swagger Spec来描述RESTful API的文件称之为Swagger specification file,它使用JSON来表述,也支持作为JSON支持的YAML。
Swagger specification file可以用来给swagger-ui生成一个Web的可交互的文档页面,以可以用swagger2markup生成静态文档,也可用使用swagger-codegen生成客户端代码。总之有了有个描述API的JSON文档之后,可以做各种扩展。
Swagger specification file可以手动编写,swagger-editor为了手动编写的工具提供了预览的功能。但是实际写起来也是非常麻烦的,同时还得保持代码和文档的两边同步。于是针对各种语言的各种框架都有一些开源的实现来辅助自动生成这个`Swagger specification file。
swagger-core是一个Java的实现,现在支持JAX-RS。swagger-annotation定义了一套注解给用户用来描述API。
spring-fox也是一个Java的实现,它支持Spring MVC, 它也支持swagger-annotation定义的部分注解。
使用
添加依赖
在pom文件添加:
<swagger.version>2.7.0</swagger.version>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>${swagger.version}</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>${swagger.version}</version>
</dependency>
配置docket
@Configuration
@EnableSwagger2
public class SwaggerConfig {
/**
* SpringBoot默认已经将classpath:/META-INF/resources/和classpath:/META-INF/resources/webjars/映射
* 所以该方法不需要重写,如果在SpringMVC中,可能需要重写定义(我没有尝试)
* 重写该方法需要 extends WebMvcConfigurerAdapter
*/
// @Override
// public void addResourceHandlers(ResourceHandlerRegistry registry) {
// registry.addResourceHandler("swagger-ui.html")
// .addResourceLocations("classpath:/META-INF/resources/");
//
// registry.addResourceHandler("/webjars/**")
// .addResourceLocations("classpath:/META-INF/resources/webjars/");
// }
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.wuwii"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Spring Boot中使用Swagger2构建RESTful APIs")
.description("rest api 文档构建利器")
.termsOfServiceUrl("https://blog.wuwii.com/")
.contact("KronChan")
.version("1.0")
.build();
}
}
builder说明
根据网上一位前辈的文章:
@Bean
public Docket petApi() {
return new Docket(DocumentationType.SWAGGER_2)
.select() //1
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build()
.pathMapping("/") //2
.directModelSubstitute(LocalDate.class, //3
String.class)
.genericModelSubstitutes(ResponseEntity.class) //4
.alternateTypeRules( //5
newRule(typeResolver.resolve(DeferredResult.class,
typeResolver.resolve(ResponseEntity.class, WildcardType.class)),
typeResolver.resolve(WildcardType.class)))
.useDefaultResponseMessages(false) //6
.globalResponseMessage(RequestMethod.GET, //7
newArrayList(new ResponseMessageBuilder()
.code(500)
.message("500 message")
.responseModel(new ModelRef("Error"))
.build()))
.securitySchemes(newArrayList(apiKey())) //8
.securityContexts(newArrayList(securityContext())) //9
;
}
方法说明:
1. 定义了需要生成API文档的endpoint,api()
方法可以通过RequestHandlerSelectors的各种选择器来选择,比如说选择所有注解了@RsestController的类中的所有API e.g. .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
。path()
方法可以通过PathSelectors的来匹配路径,提供了regex匹配或者ant匹配
2. 定义了API的根路径
3. 输出模型定义时的替换,比如遇到所有LocalDate的字段时,输出成String
4. 遇到对应泛型类型的外围类,直接解析成泛型类型,比如说ResponseEntity<T>
,应该直接输出成类型T
5. 提供了自定义性更强的针对泛型的处理,示例中的代码的意思是将类型DeferredResult直接解析成类型T
6. 是否使用默认的ResponseMessage, 框架默认定义了一些针对各个HTTP方法时各种不同响应值对应的message
7. 全局的定义ResponseMessage,示例代码定义GET方法的500错误的消息以及错误模型。注意这里GET方法的所有ResponseMessage都会被这里的定义覆盖
8. 定义API支持的SecurityScheme,指的是认证方式,支持OAuth
、APIkey
。 P.S. 要让swagger-ui的oauth正常工作,需要定义个SecurityConfiguration的Bean
9. 定义具体上下文路径对应的认证方式
10. 还有一些接口可以定义API的名称等一些基本信息,定义API支持的数据格式等等。
接口上添加文档
@RestController
@Api(description = "这是一个控制器的描述 ")
public class PetController {
/**
* logger
*/
private static final Logger LOGGER = LoggerFactory.getLogger(PetController.class);
private String no;
private String kind;
private String name;
@ApiOperation(value="测试接口", notes="测试接口描述")
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long", paramType = "path"),
@ApiImplicitParam(name = "pet", value = "宠物", required = true, dataType = "PetController")
})
@ApiResponses({
@ApiResponse(code = 200, message = "请求完成"),
@ApiResponse(code = 400, message = "请求参数错误")
})
@RequestMapping(path = "/index/{id}", method = RequestMethod.PUT)
public PetController index1(@PathVariable("id") String id, @RequestBody PetController pet) {
return pet;
}
//…… get / set
常用的注解说明
查看API文档
启动Spring Boot程序,访问:http://host:port/swagger-ui.html
。就能看到RESTful API的页面。打开我们的测试接口的API ,可以查看这个接口的描述,以及参数等信息:
点击上图中右侧的Model Schema(黄色区域:它指明了这个requestBody的数据结构),此时pet中就有了pet对象的模板,修改上测试数据,点击下方Try it out!
按钮,即可完成了一次请求调用!
调用完后,我们可以查看接口的返回信息:
参考文章
- Spring Boot中使用Swagger2构建强大的RESTful API文档档
- spring-boot-swagger2 使用手册
- 使用springfox生成springmvc项目的swagger的文档
例外补充点
验证码
我使用的是 com.github.axet.kaptcha
的验证码
虽然按照别人的方法使用 HttpServletResponse
输出流,这种是暴露 Servlet
的接口。但是发现了一个问题了,在 swagger 的获取验证码接上测试的时候不能得到验证码图片,但是在 img
标签中是没问题,发现 swagger 还是把我的返回结果作为 json
处理。所以我还是想到使用下载中二进制流的方法,将 BufferedImage
转换成二进制流数组,总算是解决。
上最后解决的办法:
/**
* 获取验证码
*/
@GetMapping(value = "/captcha.jpg", produces = MediaType.IMAGE_JPEG_VALUE)
public ResponseEntity<byte[]> captcha()throws IOException {
//生成文字验证码
String text = producer.createText();
//生成图片验证码
BufferedImage image = producer.createImage(text);
ByteArrayOutputStream out = new ByteArrayOutputStream();
ImageIO.write(image, "jpg", out);
// 文字验证码保存到 shiro session
ShiroUtils.setSessionAttribute(Constants.KAPTCHA_SESSION_KEY, text);
HttpHeaders headers = new HttpHeaders();
headers.setCacheControl("no-store, no-cache");
return ResponseEntity
.status(HttpStatus.OK)
.headers(headers)
.body(out.toByteArray());
我是采用 ImageIO
工具类的将 BufferedImage
转换成 输出流,从输出流中获取二进制流数组。
ImageIO.write(BufferedImage image,String format,OutputStream out)
再补充一个 将二进制流数组 byte[]
转换成 BufferedImage
// 将二进制流数组转换成输入流
ByteArrayInputStream in = new ByteArrayInputStream(byte[] byets);
// 读取输入流
BufferedImage image = ImageIO.read(InputStream in);
在 swagger
上是这样的了:
配置不同环境中是否启动
在不同环境种配置是否启用规则:
swagger:
enable: true # or false
在 swagger 配置类中加入
/**
* 启用
*/
@Value("${swagger.enable}")
private boolean enable;
…… set / get
配置 Docket 中
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
// 加入 enable
.enable(enable)
.select()
.apis(RequestHandlerSelectors.basePackage("com.wuwii"))
.paths(PathSelectors.any())
.build();
}
SpringMVC 中配置 Swagger2
Swagger 的配置文件:
@Configuration
@EnableSwagger2
@EnableWebMvc
@ComponentScan("com.devframe.controller")
public class SwaggerConfig extends WebMvcConfigurerAdapter {
/**
* 静态文件过滤
* @param registry
*/
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("swagger-ui.html")
.addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
}
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.devframe"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("RESTful APIs")
.description("rest api 文档构建利器")
.termsOfServiceUrl("https://blog.wuwii.com/")
.version("1.0")
.build();
}
}
额外需要在 web.xml
配置:
<!-- Springmvc前端控制器扫描路径增加“/v2/api-docs”,用于扫描Swagger的 /v2/api-docs,否则 /v2/api-docs无法生效。-->
<servlet-mapping>
<servlet-name>dispatcher</servlet-name>
<url-pattern>/v2/api-docs</url-pattern>
</servlet-mapping>
单元测试中会出现的错误
发现加入 Swagger
后,以前的单元测试再运行的时候,会抛出一个异常,参考 How to run integration tests with spring and springfox?
Caused by: org.springframework.beans.factory.UnsatisfiedDependencyException: Error creating bean with name 'documentationPluginsBootstrapper' defined in URL [jar:file:/C:/Users/test/.m2/repository/io/springfox/springfox-spring-web/2.0.0-SNAPSHOT/springfox-spring-web-2.0.0-SNAPSHOT.jar!/springfox/documentation/spring/web/plugins/DocumentationPluginsBootstrapper.class]: Unsatisfied dependency expressed through constructor argument with index 1 of type [java.util.List]: : No qualifying bean of type [org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerMapping] found for dependency [collection of org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerMapping]: expected at least 1 bean which qualifies as autowire candidate for this dependency. Dependency annotations: {}; nested exception is org.springframework.beans.factory.NoSuchBeanDefinitionException: No qualifying bean of type [org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerMapping] found for dependency [collection of org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerMapping]: expected at least 1 bean which qualifies as autowire candidate for this dependency. Dependency annotations: {}
解决,单元测试上加入 @EnableWebMvc
学习Spring Boot:(六) 集成Swagger2的更多相关文章
- 学习Spring Boot:(二十六)使用 RabbitMQ 消息队列
前言 前面学习了 RabbitMQ 基础,现在主要记录下学习 Spring Boot 整合 RabbitMQ ,调用它的 API ,以及中间使用的相关功能的记录. 相关的可以去我的博客/RabbitM ...
- Spring Boot中使用Swagger2构建RESTful APIs
关于 Swagger Swagger能成为最受欢迎的REST APIs文档生成工具之一,有以下几个原因: Swagger 可以生成一个具有互动性的API控制台,开发者可以用来快速学习和尝试API. S ...
- 学习 Spring Boot 知识看这一篇就够了
从2016年因为工作原因开始研究 Spring Boot ,先后写了很多关于 Spring Boot 的文章,发表在技术社区.我的博客和我的公号内.粗略的统计了一下总共的文章加起来大概有六十多篇了,其 ...
- 学习Spring Boot:(一)入门
微服务 现在微服务越来越火了,Spring Boot热度蹭蹭直升,自学下. 微服务其实是服务化思路的一种最佳实践方向,遵循SOA(面向服务的架构)的思路,各个企业在服务化治理上面的道路已经走得很远了, ...
- Spring Boot项目使用Swagger2文档教程
[本文版权归微信公众号"代码艺术"(ID:onblog)所有,若是转载请务必保留本段原创声明,违者必究.若是文章有不足之处,欢迎关注微信公众号私信与我进行交流!] 前言 Sprin ...
- Spring Boot中使用Swagger2构建强大的RESTful API文档
由于Spring Boot能够快速开发.便捷部署等特性,相信有很大一部分Spring Boot的用户会用来构建RESTful API.而我们构建RESTful API的目的通常都是由于多终端的原因,这 ...
- Spring Boot中使用Swagger2构建API文档
程序员都很希望别人能写技术文档,自己却很不愿意写文档.因为接口数量繁多,并且充满业务细节,写文档需要花大量的时间去处理格式排版,代码修改后还需要同步修改文档,经常因为项目时间紧等原因导致文档滞后于代码 ...
- Spring Boot中使用Swagger2自动构建API文档
由于Spring Boot能够快速开发.便捷部署等特性,相信有很大一部分Spring Boot的用户会用来构建RESTful API.而我们构建RESTful API的目的通常都是由于多终端的原因,这 ...
- 学习Spring Boot:(二十五)使用 Redis 实现数据缓存
前言 由于 Ehcache 存在于单个 java 程序的进程中,无法满足多个程序分布式的情况,需要将多个服务器的缓存集中起来进行管理,需要一个缓存的寄存器,这里使用的是 Redis. 正文 当应用程序 ...
随机推荐
- 人工智能AI芯片与Maker创意接轨 (上)
近几年来人工智能(Artificial Intelligence, AI)喴的震天价响,吃也要AI,穿也要AI,连上个厕所也要来个AI智能健康分析,生活周遭食衣住行育乐几乎无处不AI,彷佛已经来到科幻 ...
- Keycloak服务器安装和配置
安装地址:https://www.keycloak.org/archive/downloads-4.4.0.html 参考文档:https://www.keycloak.org/docs/latest ...
- 切换nPar或vPar的启动模式
在EFI Shell中执行vparconfig即可随意切换vpar和npar模式 该命令在\EFI\HPUX目录下 vparconfig 显示当前的模式 vparconfig reboo ...
- 基本数据结构 -- 栈简介(C语言实现)
栈是一种后进先出的线性表,是最基本的一种数据结构,在许多地方都有应用. 一.什么是栈 栈是限制插入和删除只能在一个位置上进行的线性表.其中,允许插入和删除的一端位于表的末端,叫做栈顶(top),不允许 ...
- 从零开始的Python学习 知识补充sorted
sorted()方法 sorted()可用于任何一个可迭代对象. 原型为sorted(iterable, cmp=None, key=None, reverse=False) iterable:一个可 ...
- Datasets
STL-10 https://cs.stanford.edu/~acoates/stl10/ CIFAR-10 and CIFAR-100 https://www.cs.toronto.edu/~kr ...
- asp.net core如何修改程序监听的端口
asp.net core 默认监听的5000和5001端口,要修改为其他端口有几种方法. 1.硬编码.优点是直观,缺点是每次修改端口都得重新编译程序. public class Program { p ...
- 备份win10的驱动程序
目录 折腾历程 怎么备份驱动 备份的驱动如何使用 关于驱动程序的OS兼容性 驱动程序的其他安装方式 1.折腾历程 从闲鱼上收了一个INSIGNIA的二合一笔记本,w7100,因原装win10性能不行自 ...
- PHP性能分析工具xdebug+qcachegrind
先安装xdebug工具 pecl install xdebug 修改php.ini配置 [xdebug] zend_extension="xdebug.so" # profiler ...
- Django_用户权限管理rbac
组成部分 1.初始化权限:login视图initial_permission,把权限信息放入session.initial_permission函数生成权限列表.菜单列表 2.中间件验证权限:在第一次 ...