Spring Boot: Spring Doc生成OpenAPI3.0文档
1. 概述
公司正好最近在整理项目的文档,且文档对于构建REST API来说是至关重要的。在这篇文章中,我将介绍Spring Doc
, 一个基于OpenAPI 3
规范简化了Spring Boot 1.x
和2.x
应用程序的API文档的生成和维护的工具。
2. 设置springdoc-openapi
如果想让 springdoc-openapi 为我们的API生成标准的 OpenAPI 3 文档, 只需要添加 [springdoc-openapi-core](https://search.maven.org/search?q=g:org.springdoc AND a:springdoc-openapi-core&core=gav) 依赖到 pom.xml:
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-core</artifactId>
<version>1.1.45</version>
</dependency>
添加完成后,启动应用程序,即可访问默认路径 /v3/api-docs
查看文档,如下所示:
http://localhost:8080/v3/api-docs/
如果想要自定义路径,可在 application.properties 文件中指定 :
springdoc.api-docs.path=/api-docs
这样,文档的访问路径就变成 :
http://localhost:8080/api-docs/
OpenAPI 默认定义为JSON 格式。对于 yaml 格式,可以访问下面的路径获取 :
http://localhost:8080/api-docs.yaml
3.整合springdoc-openapi 和Swagger UI
除了自己生成OpenAPI 3
规范外,我们还可以将springdoc-openapi
与Swagger UI
集成在一起,以便可以与我们的API规范进行交互并测试端点。
3.1. Maven 依赖
要整合springdoc-openapi
和 Swagger UI
, 唯一要做的就是添加springdoc-openapi-ui
依赖到项目pom.xml文件中。
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId>
<version>1.1.45</version>
</dependency>
访问swagger-ui页面:
http://localhost:8080/swagger-ui.html
当然也可以像上面一样,自定义访问路径:
springdoc.swagger-ui.path=/swagger-ui-custom.html
3.2. 举个栗子
假设有个球(国足令人伤心,所以需要个球啊!!)的controller。
@RestController
@RequestMapping("/api/ball")
public class BallController {
@Autowired
private BallRepository repository;
@GetMapping("/{id}")
public Ball findById(@PathVariable long id) {
return repository.findById(id)
.orElseThrow(() -> new BallNotFoundException());
}
@GetMapping("/")
public Collection<Book> findBooks() {
return repository.getBooks();
}
@PutMapping("/{id}")
@ResponseStatus(HttpStatus.OK)
public Book updateBook(@PathVariable("id") final String id, @RequestBody final Book book) {
return book;
}
}
启动项目,在浏览器中访问地址:
http://localhost:8080/swagger-ui-custom.html
swagger-ui的界面:
4. springdoc-openapi 与Spring WebFlux集成
我们可以在Spring WebFlux 项目中通过添加依赖:springdoc-openapi-webflux-ui
与springdoc-openapi
and Swagger UI
集成:
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-webflux-ui</artifactId>
<version>1.1.45</version>
</dependency>
然后,浏览器访问地址
http://localhost:8080/swagger-ui.html
同样的,可以通过添加 springdoc.swagger-ui.path 配置项到 application.properties文件来自定义文档访问路径。
5. 使用springdoc-openapi
Maven 插件
springdoc-openapi
库提供了 springdoc-openapi-maven-plugin插件,用来生成JSON或者yaml格式的Open API 描述。
springdoc-openapi-maven-plugin 依赖于 spring-boot-maven 插件. Maven在集成测试阶段运行openapi插件。
那么,如何在pom.xml
中配置插件呢?请看下面的代码:
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<version>2.1.8.RELEASE</version>
<executions>
<execution>
<id>pre-integration-test</id>
<goals>
<goal>start</goal>
</goals>
</execution>
<execution>
<id>post-integration-test</id>
<goals>
<goal>stop</goal>
</goals>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-maven-plugin</artifactId>
<version>0.2</version>
<executions>
<execution>
<phase>integration-test</phase>
<goals>
<goal>generate</goal>
</goals>
</execution>
</executions>
</plugin>
当然, 也可以用自定义值来配置插件:
<plugin>
<executions>
.........
</executions>
<configuration>
<apiDocsUrl>http://localhost:8080/v3/api-docs</apiDocsUrl>
<outputFileName>openapi.json</outputFileName>
<outputDir>${project.build.directory}</outputDir>
</configuration>
</plugin>
仔细看看我们在插件中配置的几个参数:
- apiDocsUrl – 访问json格式文档的URL, 默认路径:http://localhost:8080/v3/api-docs
- outputFileName – 存放定义的路径, 默认为: openapi.json
- outputDir – 文档存放的绝对路径–默认为: ${project.build.directory}
6. 使用 JSR-303 Bean Validation 自动生成文档
当我们在模型中使用 JSR-303 bean validation 注解, 诸如 @NotNull, @NotBlank, @Size, @Min, @Max等, springdoc-openapi 会为这些bean生成相应的约束。
举个栗子:
public class Ball {
private long id;
@NotBlank
@Size(min = 0, max = 20)
private String title;
@NotBlank
@Size(min = 0, max = 30)
private String author;
}
为Ball bean生成的文档内容更为丰富:
7. 使用 @ControllerAdvice和@ResponseStatus生成文档
在@RestControllerAdvice注解的类中,在方法上使用@ResponseStatus会自动生成带有返回状态码的文档。如以下被@ControllerAdvice
注解的类中,@ResponseStatus修饰的两个方法:
@RestControllerAdvice
public class GlobalControllerExceptionHandler {
@ExceptionHandler(ConversionFailedException.class)
@ResponseStatus(HttpStatus.BAD_REQUEST)
public ResponseEntity<String> handleConnversion(RuntimeException ex) {
return new ResponseEntity<>(ex.getMessage(), HttpStatus.BAD_REQUEST);
}
@ExceptionHandler(BallNotFoundException.class)
@ResponseStatus(HttpStatus.NOT_FOUND)
public ResponseEntity<String> handleBallNotFound(RuntimeException ex) {
return new ResponseEntity<>(ex.getMessage(), HttpStatus.NOT_FOUND);
}
}
现在我们可以在文档中看到返回状态码为400和404。
8. 小结
Spring Boot 2.2.x版本目前可能不支持,因此使用时最好使用2.1.x ,本文所使用Spring Boot版本 2.1.8.RELEASE。
以上代码可在我的github中找到, over on GitHub.
关注公众号: 回复666 领取翻译文章福利:
Spring Boot: Spring Doc生成OpenAPI3.0文档的更多相关文章
- Spring Boot 集成 Swagger 生成 RESTful API 文档
原文链接: Spring Boot 集成 Swagger 生成 RESTful API 文档 简介 Swagger 官网是这么描述它的:The Best APIs are Built with Swa ...
- spring boot使用swagger生成api接口文档
前言 在之前的文章中,使用mybatis-plus生成了对应的包,在此基础上,我们针对项目的api接口,添加swagger配置和注解,生成swagger接口文档 具体可以查看本站spring boot ...
- Spring Boot 集成Swagger2生成RESTful API文档
Swagger2可以在写代码的同时生成对应的RESTful API文档,方便开发人员参考,另外Swagger2也提供了强大的页面测试功能来调试每个RESTful API. 使用Spring Boot可 ...
- Spring Boot中使用Swagger2构建API文档
程序员都很希望别人能写技术文档,自己却很不愿意写文档.因为接口数量繁多,并且充满业务细节,写文档需要花大量的时间去处理格式排版,代码修改后还需要同步修改文档,经常因为项目时间紧等原因导致文档滞后于代码 ...
- 【spring boot】application.properties官方完整文档【参考使用】
官方地址: https://docs.spring.io/spring-boot/docs/current-SNAPSHOT/reference/htmlsingle/ 进入搜索: Appendice ...
- 【spring boot】application.properties官方完整文档
官方地址: https://docs.spring.io/spring-boot/docs/current-SNAPSHOT/reference/htmlsingle/ 进入搜索: Appendice ...
- 《Spring Boot 实战纪实》之关键点文档
目录 前言 (思维篇)人人都是产品经理 1.需求文档 1.1 需求管理 1.2 如何攥写需求文档 1.3 需求关键点文档 2 原型设计 2.1 缺失的逻辑 2.2 让想法跃然纸上 3 开发设计文档 3 ...
- Spring Boot2配置Swagger2生成API接口文档
一.Swagger2介绍 前后端分离开发模式中,api文档是最好的沟通方式. Swagger 是一个规范和完整的框架,用于生成.描述.调用和可视化 RESTful 风格的 Web 服务. 及时性 (接 ...
- Spring Boot学习笔记 - 整合Swagger2自动生成RESTful API文档
1.添加Swagger2依赖 在pom.xml中加入Swagger2的依赖 <!--swagger2--> <dependency> <groupId>io.spr ...
随机推荐
- python编程系列---白痴女朋友(我没有女朋友!)看了都能懂的TCP/IP协议介绍
前言 早期的计算机网络,都是由各厂商自己规定一套协议,IBM.Apple和Microsoft都有各自的网络协议,互不兼容:为了把全世界的所有不同类型的计算机都连接起来,就必须规定一套全球通用的协议,为 ...
- PostgreSQL使用安装
PostgreSQL使用安装 一. 安装 ubuntu安装: # 安装客户端 sudo apt-get install postgresql-client # 安装服务器 sudo apt-get i ...
- openresty性能测试报告分析
一.openresty介绍 1.什么是openresty 通过揉和众多设计良好的 Nginx 模块,OpenResty 有效地把 Nginx 服务器转变为一个强大的 Web 应用服务器,基于它开发人员 ...
- The usage of Markdown---链接的使用
目录 1. 序言 2. 网页链接 3. 图片链接 4. 页内跳转 更新时间:2019.09.14 1. 序言 在编辑文章的时候,我们常常需要插入各种链接,比如说网页链接,图片链接等等.当文章篇幅过 ...
- 四、pymysql模块、索引和慢查询
目录 一.pymysql模块 (一)如何使用 (二)sql注入问题 二.索引 (一)主键索引 (二)唯一索引 (三)普通索引 (四)联合索引 (五)不会命中索引的情况 (六)explain (七)索引 ...
- 关于./xhost: unable to open display问题的解决
看了很多大同小异的帖子,都没能解决这个问题,以下是我的实测经验,注意第三步,很关键. 注:以下操作在确保vncserver.xdpyinfo服务正常的情况下进行 第一步:root登录,启动vncser ...
- WinDag基础1
建立调试会话 用户层调试会话的建立 直接创建进程并调试 附加到已经打开的进程 侵入式附加:接管正在运行的进程,可以进行调试 非侵入式附加:只能读取进程信息,不能接收目标进程的调试事件 通常情况下一个程 ...
- 12 Zabbix4.4.0系统sendEmail邮件报警优化
点击返回:自学Zabbix之路 点击返回:自学Zabbix4.0之路 点击返回:自学zabbix集锦 12 Zabbix4.4.0系统sendEmail邮件报警优化 接上一章节 Zabbix4.4. ...
- [2018-10-29] python开发个人资源共享网--第二天
创建Django目录 startproject my_project 创建APP startapp my_app 手动创建的文件夹 log 日志 media 用户上传下载 static 静态文件 配置 ...
- windows下如何安装Python虚拟环境
1.前言 由于Python的版本众多,还有Python2和Python3的争论,因此有些软件包或第三方库就容易出现版本不兼容的问题. 通过 virtualenv 这个工具,就可以构建一系列虚拟的Pyt ...