1. 概述

公司正好最近在整理项目的文档,且文档对于构建REST API来说是至关重要的。在这篇文章中,我将介绍Spring Doc , 一个基于OpenAPI 3规范简化了Spring Boot 1.x2.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-openapiSwagger UI集成在一起,以便可以与我们的API规范进行交互并测试端点。

3.1. Maven 依赖

要整合springdoc-openapiSwagger 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-uispringdoc-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文档的更多相关文章

  1. Spring Boot 集成 Swagger 生成 RESTful API 文档

    原文链接: Spring Boot 集成 Swagger 生成 RESTful API 文档 简介 Swagger 官网是这么描述它的:The Best APIs are Built with Swa ...

  2. spring boot使用swagger生成api接口文档

    前言 在之前的文章中,使用mybatis-plus生成了对应的包,在此基础上,我们针对项目的api接口,添加swagger配置和注解,生成swagger接口文档 具体可以查看本站spring boot ...

  3. Spring Boot 集成Swagger2生成RESTful API文档

    Swagger2可以在写代码的同时生成对应的RESTful API文档,方便开发人员参考,另外Swagger2也提供了强大的页面测试功能来调试每个RESTful API. 使用Spring Boot可 ...

  4. Spring Boot中使用Swagger2构建API文档

    程序员都很希望别人能写技术文档,自己却很不愿意写文档.因为接口数量繁多,并且充满业务细节,写文档需要花大量的时间去处理格式排版,代码修改后还需要同步修改文档,经常因为项目时间紧等原因导致文档滞后于代码 ...

  5. 【spring boot】application.properties官方完整文档【参考使用】

    官方地址: https://docs.spring.io/spring-boot/docs/current-SNAPSHOT/reference/htmlsingle/ 进入搜索: Appendice ...

  6. 【spring boot】application.properties官方完整文档

    官方地址: https://docs.spring.io/spring-boot/docs/current-SNAPSHOT/reference/htmlsingle/ 进入搜索: Appendice ...

  7. 《Spring Boot 实战纪实》之关键点文档

    目录 前言 (思维篇)人人都是产品经理 1.需求文档 1.1 需求管理 1.2 如何攥写需求文档 1.3 需求关键点文档 2 原型设计 2.1 缺失的逻辑 2.2 让想法跃然纸上 3 开发设计文档 3 ...

  8. Spring Boot2配置Swagger2生成API接口文档

    一.Swagger2介绍 前后端分离开发模式中,api文档是最好的沟通方式. Swagger 是一个规范和完整的框架,用于生成.描述.调用和可视化 RESTful 风格的 Web 服务. 及时性 (接 ...

  9. Spring Boot学习笔记 - 整合Swagger2自动生成RESTful API文档

    1.添加Swagger2依赖 在pom.xml中加入Swagger2的依赖 <!--swagger2--> <dependency> <groupId>io.spr ...

随机推荐

  1. python编程系列---白痴女朋友(我没有女朋友!)看了都能懂的TCP/IP协议介绍

    前言 早期的计算机网络,都是由各厂商自己规定一套协议,IBM.Apple和Microsoft都有各自的网络协议,互不兼容:为了把全世界的所有不同类型的计算机都连接起来,就必须规定一套全球通用的协议,为 ...

  2. PostgreSQL使用安装

    PostgreSQL使用安装 一. 安装 ubuntu安装: # 安装客户端 sudo apt-get install postgresql-client # 安装服务器 sudo apt-get i ...

  3. openresty性能测试报告分析

    一.openresty介绍 1.什么是openresty 通过揉和众多设计良好的 Nginx 模块,OpenResty 有效地把 Nginx 服务器转变为一个强大的 Web 应用服务器,基于它开发人员 ...

  4. The usage of Markdown---链接的使用

    目录 1. 序言 2. 网页链接 3. 图片链接 4. 页内跳转 更新时间:2019.09.14 1. 序言   在编辑文章的时候,我们常常需要插入各种链接,比如说网页链接,图片链接等等.当文章篇幅过 ...

  5. 四、pymysql模块、索引和慢查询

    目录 一.pymysql模块 (一)如何使用 (二)sql注入问题 二.索引 (一)主键索引 (二)唯一索引 (三)普通索引 (四)联合索引 (五)不会命中索引的情况 (六)explain (七)索引 ...

  6. 关于./xhost: unable to open display问题的解决

    看了很多大同小异的帖子,都没能解决这个问题,以下是我的实测经验,注意第三步,很关键. 注:以下操作在确保vncserver.xdpyinfo服务正常的情况下进行 第一步:root登录,启动vncser ...

  7. WinDag基础1

    建立调试会话 用户层调试会话的建立 直接创建进程并调试 附加到已经打开的进程 侵入式附加:接管正在运行的进程,可以进行调试 非侵入式附加:只能读取进程信息,不能接收目标进程的调试事件 通常情况下一个程 ...

  8. 12 Zabbix4.4.0系统sendEmail邮件报警优化

    点击返回:自学Zabbix之路 点击返回:自学Zabbix4.0之路 点击返回:自学zabbix集锦 12 Zabbix4.4.0系统sendEmail邮件报警优化 接上一章节  Zabbix4.4. ...

  9. [2018-10-29] python开发个人资源共享网--第二天

    创建Django目录 startproject my_project 创建APP startapp my_app 手动创建的文件夹 log 日志 media 用户上传下载 static 静态文件 配置 ...

  10. windows下如何安装Python虚拟环境

    1.前言 由于Python的版本众多,还有Python2和Python3的争论,因此有些软件包或第三方库就容易出现版本不兼容的问题. 通过 virtualenv 这个工具,就可以构建一系列虚拟的Pyt ...