spring boot api文档_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 {@Autowiredprivate 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的界面:
https://www.baeldung.com/wp-content/uploads/2019/11/1-swagger-ui.png
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 领取翻译文章福利:
http://weixin.qq.com/r/_zvI0CDEeX0GrWSz927p (二维码自动识别)
叮叮叮!关注公众号: 锅外的大佬 ,加入锅外圈,不定时福利输出,hi欢迎你的加入哦 私人博客地址: http://www.developlee.top
spring boot api文档_Spring Boot: Spring Doc生成OpenAPI3.0文档相关推荐
- idea swagger生成接口文档_spring boot集成Swagger-UI接口文档
本文介绍如何用spring boot集成Swagger-UI,实现项目在线接口文档 一.Swagger-UI简介 Swagger是一个Restful风格接口的文档在线自动生成和测试的框架 官网对Swa ...
- boot spring test 文档_Spring、Spring Boot 和 TestNG 测试指南 ( 3 )
原标题:Spring.Spring Boot 和 TestNG 测试指南 ( 3 ) 来源:chanjarster, github.com/chanjarster/spring-test-exampl ...
- idea swagger生成接口文档_Spring Boot(九)Swagger2自动生成接口文档和Mock模拟数据...
一.简介 在当下这个前后端分离的技术趋势下,前端工程师过度依赖后端工程师的接口和数据,给开发带来了两大问题: 问题一.后端接口查看难:要怎么调用?参数怎么传递?有几个参数?参数都代表什么含义? 问题二 ...
- oracle帮助文档_Spring Boot Config文档,使用IntelliJ IDEA的两种方法
一个Spring Boot文档,两种方式. 在优锐课的java沙龙分享中,在现代软件开发中,应用程序由配置驱动. 如果可配置属性的数量很大,则很难记住每个属性的用途,结构或类型. 因此,有必要对这些属 ...
- spring定时每天早上八点_Spring Boot教程(13) – 简单定时任务
"每隔几分钟执行一个任务"这种需求,几乎在每个项目里都有可能遇到.Spring框架提供了一种简单的方式来完成这一需求.你只需要在定时执行的方法上加上注解就行了. 首先你需要开启这一 ...
- spring日志报错提醒_Spring Boot 2.x : 整合日志框架 Log4j2
日志框架概述 在一个 web 项目建设中,如果说第一件事是 Spring 框架的搭建,那么第二件事就是日志框架的搭建,线上 web 项目的日志可能是我们了解项目运行的唯一方式. 常用日志框架 java ...
- spring jpa mysql集群_Spring Boot系列之十四 JPA 连接mycat
接 本文介绍使用spring-data-jpa连接mycat实现应用的读写分离. 系统环境spring-boot 1.4.3-RELEASE jdk1.8 进入正题application.yml配置文 ...
- gradle官方文档_Spring Boot+Gradle+MyBatisPlus3.x搭建企业级的后台分离框架
你再主动一点点 我们就有故事了 原文:toutiao.com/i6861456496740270604 1.技术选型 解析器:FastJSON 开发工具:JDK1.8 .Gradle.IDEA 技 ...
- boot sprint 项目结构_Spring Boot 项目结构
(1)代码层的结构 根目录:com.springboot 1.工程启动类(Application.java)置于com.springboot.build包下 2.实体类(domain)置于com.sp ...
最新文章
- C++中模板template typename T
- Python使用数字与字符串的技巧
- 企业架构(五)——联邦企业架构(FEA)实施指南
- 虚拟机——虚拟机的初步认识
- TensorFlow Lite 正式发布,谷歌移动端深度学习框架
- iphone屏幕突然变暗_iPhone 玩游戏时屏幕突然变暗,来看看是什么原因?
- Anaconda3的安装
- Spring高级之注解@DependsOn详解(超详细)
- 【文件系统】NTFS、FAT32、exFAT
- Cookie介绍与操作
- Doris之备份与恢复(全面)
- badboy设置中文_录制脚本badboy工具使用手册
- 国外不错的模板素材网站
- 【kubernetes/k8s概念】CNI详解
- IE浏览器下载中文文件,文件名乱码或变成下划线问题
- 信息安全三要素(CIA):
- 淘宝新店运营怎么选品?API接口助您高效选品
- 二维空间最近点对问题 python
- 音痴测试软件,测试你是一个五音不全的音痴吗
- Virtualbox虚拟机运行加速