春季最高

通过参考,使用Spring 5和Spring Boot 2开始学习的春天课程:

>>学习春天
休息顶部

通过参考,使用Spring 5和Spring Boot 2开始学习的春天课程:

>>查看课程

1.概述

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

进一步阅读:

用摇摇晃晃地生成弹簧启动休息客户端

了解如何使用Swagger Code生成器生成Spring Boot REST客户端。

使用Spring REST API设置Swagger 2

了解如何使用Swagger 2记录Spring REST API。

春天云合同介绍

学习使用春云合同编写和测试消费者驱动的合同。

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
昂首阔步的UI

让我们钻到/ api /书端点并查看其请求和响应的详细信息:
Swagger UI 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描述jsonyaml.格式。

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)私有字符串作者;}

控件生成的文档豆有点内容:
添加bean验证后的书架架构

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的文档:
@ControllAde和@ResponseStatus的文档

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

春天底

使用Spring 5和Spring Boot 2开始,通过学习的春天课程:

> >这门课程
休息底部

使用Spring 5和Spring Boot 2开始,通过学习的春天课程:

>>查看课程
8.注释
最古老的
最新的
内联反馈
查看所有评论
对这篇文章的评论关闭!