使用OpenAPI 3.0记录Spring Rest API
最后修改:2021年1月30日
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 groupID> SpringDoc-OpenAPI-UI Artifactid> 1.5.2 version> 依赖项>
然后,当我们运行我们的应用程序时,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 groupID> SpringDoc-OpenAPI-UI Artifactid> 1.5.2 version> 依赖项>
现在我们可以访问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 groupID> SpringDoc-OpenAPI-WebFlux-UI ArtifactiD> 1.5.2 version> 依赖项>
和以前一样,这些文档可以在以下网址找到:
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 groupID> SpringDoc-OpenAPI-Data-Rest Artifactid> 1.5.2 version> 依赖项>
现在它将预期的查询参数添加到文档:

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 groupID> Spring-Boot-Maven-Plugin Artifactid> 2.3.3.Release version> <执行> <执行> 预集成 - 测试 id> <目标> <目标>启动目标> 目标> 执行> <执行> 后集成 - test id> stop目标> 目标> 执行> 执行> plugin> org.springdoc groupID> SpringDoc-OpenApi-Maven-Plugin ArtifactiD> 0.2 version> <执行> <执行> <阶段>集成 - 测试阶段> <目标> <目标>生成目标> 目标> 执行> executions> plugin>
我们还可以配置插件以使用自定义值:
<执行> ......... 执行> http:// localhost:8080 / v3 / api-docs apidocsurl> openapi.json $ {project.build.directory} outputdir> configuration> plugin>
让我们仔细看看可以为插件配置的参数:
- 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);}}
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。