使用OpenAPI 3.0记录Spring Rest API

1.概述

文档是构建REST api的重要组成部分。在本教程中，我们将看看SpringDoc——一个基于Spring Boot 1的OpenAPI 3规范的简化API文档生成和维护的工具。x和2。x应用程序。

2.设置springdoc-openapi

有Springdoc-Openapi.为我们的API自动生成OpenAPI 3规范文档，我们只是添加了Springdoc-OpenApi-UI依赖我们pom.xml.：

<依赖项>  org.springdoc   SpringDoc-OpenAPI-UI   1.5.2  

然后，当我们运行我们的应用程序时，Dopapi描述将在路径上使用/ v3 / api-docs默认情况下:

http://localhost:8080/v3/api-docs/

要使用自定义路径，可以在application.properties.文件：

springdoc.api-docs.path = / api文档

现在我们将能够访问文档：

http：// localhost：8080 / api-docs /

openapi定义是json默认格式。为yaml.格式，我们可以在:

http://localhost:8080/api-docs.yaml

3.使用播放UI设置SpringDoc-Openapi

除了生成OpenAPI 3规范本身外，我们可以与Swagger UI集成SpringDoc-OpenAPI，以便我们可以与我们的API规范进行交互并锻炼端点。

3.1。Maven的依赖

我们必须做的就是使用Swagger UI设置SpringDoc-Openapi是添加依赖项Springdoc-OpenApi-UI到项目的pom.xml.：

<依赖项>  org.springdoc   SpringDoc-OpenAPI-UI   1.5.2  

现在我们可以访问API文档：

http：// localhost：8080 / swagger-ui.html

3.2。支持swagger-ui特性

SpringDoc-OpenAPI也支持swagger-ui特性。这些可以用作春天引导属性，其中包含前缀springdoc.swagger-ui。

例如，让我们定制API文档的路径。我们可以通过修改application.properties.包括：

springdoc.swagger-ui.path = / swagger-ui-custom.html

所以现在我们的API文档将可用http://localhost:8080/swagger-ui-custom.html。

作为另一个例子，为了按顺序对API路径进行排序，我们可以添加：

springdoc.swagger-ui.operationssorter =方法

3.3。示例API

假设我们的应用程序有一个用于管理的控制器书S：

@RestController @RequestMapping("/api/book") public class BookController {@Autowired private BookRepository repository;@GetMapping("/{id}") public Book findById(@PathVariable long id) {return repository.findById(id) .orElseThrow(() -> new BookNotFoundException());} @GetMapping("/") public Collection 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

让我们钻到/ api /书端点并查看其请求和响应的详细信息：

4.使用Spring WebFlux集成SpringDoc-Openapi

我们可以通过添加将SpringDoc-Openapi和Swigger UI集成在Spring WebFlux项目中springdoc-openapi-webflux-ui：

<依赖项>  org.springdoc   SpringDoc-OpenAPI-WebFlux-UI   1.5.2  

和以前一样，这些文档可以在以下网址找到:

http：// localhost：8080 / swagger-ui.html

为了定制路径，我们可以再次添加springdoc.swagger-ui.path.在我们的财产application.properties.。

5.暴露分页信息

Spring Data JPA无缝地与Spring MVC集成。这种集成的一个例子是可分页支持：

@GetMapping("/filter") public Page filterBooks(Pageable Pageable) {return repository.getBooks(Pageable);}

起初我们可能会期望springdoc添加页那尺寸， 和种类查询生成文档的参数。然而，默认情况下，SpringDoc并没有满足这个期望。为了解锁这个功能，我们应该添加SpringDoc-OpenApi-Data-Rest依赖:

<依赖项>  org.springdoc   SpringDoc-OpenAPI-Data-Rest   1.5.2  

现在它将预期的查询参数添加到文档：

6.使用SpringDoc-OpenAPI Maven插件

SpringDoc-OpenAPI库提供了一个Maven插件springdoc-openapi-maven-plugin中生成OpenAPI描述json和yaml.格式。

这springdoc-openapi-maven-plugin插件适用于spring-boot-maven插件。Maven运行openapi插件在集成测试阶段。

让我们看看我们如何配置插件pom.xml.：

  org.springframework.boot   Spring-Boot-Maven-Plugin   2.3.3.Release  <执行> <执行> 预集成 - 测试 <目标> <目标>启动   <执行> 后集成 -  test    stop       org.springdoc   SpringDoc-OpenApi-Maven-Plugin  0.2  <执行> <执行> <阶段>集成 - 测试 <目标> <目标>生成    

我们还可以配置插件以使用自定义值：

 <执行> .........    http：// localhost：8080 / v3 / api-docs   openapi.json   $ {project.build.directory}   

让我们仔细看看可以为插件配置的参数：

• apiDocsUrl- URL可以以JSON格式访问文档，其中默认值http：// localhost：8080 / v3 / api-docs
• outputfilename.- 存储定义的文件的名称，默认为OpenApi.json.
• outputdir.—默认情况下，文档所在目录的绝对路径$ {project.build.directory}

7.使用JSR-303 Bean验证自动生成文档

当我们的模型包含JSR-303 bean验证注释时，例如@NotNull那@notblank.那@尺寸那@min.， 和@Max，SpringDoc-OpenAPI库使用它们来为相应的约束生成其他架构文档。

让我们来看一个使用书豆:

公共班级书{私人长号;@notblank @size（min = 0，max = 20）私有字符串标题;@notblank @size（min = 0，max = 30）私有字符串作者;}

控件生成的文档书豆有点内容：

8.使用文件生成文档@ControllerAdvice和@ResponseStatus

使用@ResponseStatus方法中的@RestControllAdvice.类将自动为响应代码生成文档。在这个@RestControllAdvice.类，这两种方法都被注释了@ResponseStatus：

@RestControllAdePullult GlobalControlleExceptionHandler {@ExceptionHandler（ConversionFailEdException.class）@ResponseStatus（httpstatus.bad_request）publical andertentity  handleconnversion（runtimeexception ex）{return new andertentity <>（exgetmessage（），httpstatus.bad_request）;} @ExceptionHandler（BookNotFoundException.class）@ResponseStatus（httpstatus.not_found）public alynateTentity  supperbooknotfound（runtimeexception ex）{return new andertentity <>（exgetmessage（），httpstatus.not_found）;}}

因此，我们现在可以看到响应代码400和404的文档：

9.生成的文档使用@手术和@apiresponses.

接下来让我们看看我们如何使用几个描述对我们的API添加一些描述特定openapi的注释。

为此，我们将向我们的控制器注释/ api / book / {id}端点与@手术和@apiresponses.：

@operation（summary =“通过其ID获取一本书”）@apiresponses（value = {@apiresponse（contoptecode =“200”，description =“找到了本书”，content = {@content（Mediatype =“Application / Json”那schema = @Schema(implementation = Book.class)) }), @ApiResponse(responseCode = "400", description = "Invalid id supplied", content = @Content), @ApiResponse(responseCode = "404", description = "Book not found", content = @Content) }) @GetMapping("/{id}") public Book findById(@Parameter(description = "id of book to be searched") @PathVariable long id) { return repository.findById(id).orElseThrow(() -> new BookNotFoundException()); }

这是效果：

我们可以看到，我们添加的文字@手术放置在API操作水平。同样，描述添加到各种各样的@apiresponse.元素在@apiresponses.容器注释在这里也可见，为我们的API响应添加了意义。

显然，我们没有得到上述响应400和404的任何模式。正如我们定义的空@内容对于他们而言，只显示他们的描述。

10.芬兰湾的科特林支持

由于Spring Boot 2.x对Kotlin具有一流的支持，SpringDoC支持引导2.x应用程序的框中的此JVM语言。

为了查看实际操作，我们将创建一个简单的FooAPI在Kotlin。

之后初始设置，我们将添加一个数据类和一个控制器。我们会把它们添加到Boot App的子包中，这样当它运行时，它会选择我们的FooController跟早一点一起起来BookController.：

@entity数据类foo（@idval id：long = 0，@notblank @size（min = 0，max = 50）val name：string =“”）@restcontroller @requestmapping（“/”）class foocontroller（）{val傻瓜：list = listof（foo（1，“一”），foo（2，“两个”））@operation（summary =“get所有foos”）@apiresponses（value = [apiresponse（contopecode =“200”，Description =“找到foos”，content = [（contentype =“application / json”，array =（arrayschema（schema = schema（Schemape = foo :: class）））），apiresponse（respectecode =“400“，描述=”错误请求“，content = [content（）]），apiresponse（contenceecode =”404“，描述=”没有找到任何foos“，content = [content（）]）]）@getmapping（”/ foo“）有趣getAllfoos（）：list =愚蠢师}

现在，当我们点击API文档URL时，我们将看到FooAPI:

为了增强对Kotlin类型的支持，我们可以添加以下依赖项:

<依赖> < groupId > org。springdoc-openapi-kotlin1.3.9 

在那之后，我们的Foo模式看起来更有用，就像我们添加JSR-303 Bean验证时那样:

11.结论

在本文中，我们学习了如何在项目中设置springdoc-openapi。然后我们看到了如何将springdoc-openapi与Swagger UI集成。我们还看到了如何在Spring Webflux项目中做到这一点。

接下来，我们使用springdoc-openapi Maven Plugin为我们的api生成OpenAPI定义，并了解了如何从Spring Data公开分页和排序信息。之后，我们研究了springdoc-openapi如何使用JSR 303 bean验证注释和@ResponseStatus注释在@ControllerAdvice班级。

我们还学习了如何使用一些特定于OpenApi的注释为我们的API添加描述。最后，我们在Openapi对Kotlin的支持下偷看了。

SpringDoc-OpenAPI根据OpenAPI 3规范生成API文档。此外，它还处理我们的Swagger UI配置，使API文档生成一个相当简单的任务。

与往常一样，代码是可用的在GitHub。