使用 Spring Doc 为 Spring REST API 生成 OpenAPI 3.0 文档 | 您所在的位置:网站首页 › 常用api接口开放文档 › 使用 Spring Doc 为 Spring REST API 生成 OpenAPI 3.0 文档 |
1、概览
文档是构建 REST API 的重要组成部分。在本教程中,我们将介绍 Spring Doc,它可简化 API 文档的生成和维护,这些文档基于 OpenAPI 3 规范,适用于 Spring Boot 3.x 应用程序。 2、设置 springdoc-openapiSpring Boot 3.x 要求使用 springdoc-openapi version 2: org.springdoc springdoc-openapi-starter-webmvc-ui 2.1.0 2.1、 OpenAPI 描述的路径正确设置依赖后,我们就可以运行应用程序,并在 /v3/api-docs 路径访问 OpenAPI 描述,这是默认路径: http://localhost:8080/v3/api-docs此外,我们还可以使用 springdoc.api-docs 属性在 application.properties 中自定义描述的路径。例如,我们可以将路径设置为 /api-docs: springdoc.api-docs.path=/api-docs然后,我们就可以通过以下网址访问文档描述: http://localhost:8080/api-docsOpenAPI 描述定义默认为 JSON 格式。对于 yaml 格式,我们可以从以下网址获取定义: http://localhost:8080/api-docs.yaml 3、整合 Swagger UI除了生成 OpenAPI 3 规范之外,我们还可以将 springdoc-openapi 与 Swagger UI 集成,以与我们的 API 规范进行交互并测试端点。 Springdoc-openapi 依赖项中已经包含了 Swagger UI,因此我们可以通过如下路径访问 API 文档: http://localhost:8080/swagger-ui/index.html 3.1、对 swagger-ui properties 的支持springdoc-openapi 库还支持 swagger-ui properties。这些属性可作为 Spring Boot 属性使用,前缀为 springdoc.swagger-ui。 例如,我们可以通过更改 application.properties 文件中的 springdoc.swagger-ui.path 属性,自定义 API 文档的路径: springdoc.swagger-ui.path=/swagger-ui-custom.html现在我们的 API 文档可以通过 http://localhost:8080/swagger-ui-custom.html 访问。 再比如,我们可以使用 springdoc.swagger-ui.operationsSorter 属性根据 HTTP 方法对 API 路径进行排序: springdoc.swagger-ui.operationsSorter=method 3.2、示例 API假设我们的应用程序有一个管理 Book 的 controller: @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/book 端点,查看其请求和响应的详细信息: 4、整合 springdoc-openapi 与 Spring WebFlux我们还可以在 Spring WebFlux 应用上轻松整合 springdoc-openapi 和 Swagger UI(springdoc.swagger-ui properties 也可用)。只需要在 pom.xml 文件中添加 springdoc-openapi-webflux-ui 依赖: org.springdoc springdoc-openapi-starter-webflux-ui 2.1.0 5、显示分页信息Spring Data JPA 与 Spring MVC 无缝集成。例如,对 Pageable 的支持: @GetMapping("/filter") public Page filterBooks(@ParameterObject Pageable pageable) { return repository.getBooks(pageable); }自 springdoc-openapi v1.6.0 起,Pageable 支持已开箱即用。page、size 和 sort 查询参数会添加到生成的文档中: 6、使用 springdoc-openapi Maven 插件springdoc-openapi 库提供了一个 Maven 插件 springdoc-openapi-maven-plugin,可生成 JSON 和 YAML 格式的 OpenAPI 描述。 springdoc-openapi-maven-plugin 插件与 spring-boot-maven 插件配合使用。Maven 会在 integration-test 阶段运行 openapi 插件。 让我们看看如何在 pom.xml 中配置插件: org.springframework.boot spring-boot-maven-plugin 2.3.3.RELEASE pre-integration-test start post-integration-test stop org.springdoc springdoc-openapi-maven-plugin 1.4 integration-test generate我们还可以对插件进行配置,以使用自定义值: ......... http://localhost:8080/v3/api-docs openapi.json ${project.build.directory}插件配置的参数如下: apiDocsUrl:访问 JSON 格式文档的 URL,默认为 http://localhost:8080/v3/api-docs outputFileName:存储定义的文件名;默认为 openapi.json outputDir:文档存储目录的绝对路径;默认为 ${project.build.directory} 7、使用 JSR-303 Bean Validation 自动生成文档当我们的 model 包含 JSR-303 Bean 验证注解(如 @NotNull、@NotBlank、@Size、@Min 和 @Max)时,springdoc-openapi 库会使用它们为相应的约束生成额外的 schema 文档。 让我们用图书 Book bean 来举个例子: public class Book { private long id; @NotBlank @Size(min = 0, max = 20) private String title; @NotBlank @Size(min = 0, max = 30) private String author; }现在,为 Book Bean 生成的文档信息量更大了: 8、使用 @ControllerAdvice 和 @ResponseStatus 生成文档在 @RestControllerAdvice 类中的方法上使用 @ResponseStatus 会自动为 response code 生成文档。在这个 @RestControllerAdvice 类中,两个方法都注解了 @ResponseStatus: @RestControllerAdvice public class GlobalControllerExceptionHandler { @ExceptionHandler(ConversionFailedException.class) @ResponseStatus(HttpStatus.BAD_REQUEST) public ResponseEntity handleConversion(RuntimeException ex) { return new ResponseEntity(ex.getMessage(), HttpStatus.BAD_REQUEST); } @ExceptionHandler(BookNotFoundException.class) @ResponseStatus(HttpStatus.NOT_FOUND) public ResponseEntity handleBookNotFound(RuntimeException ex) { return new ResponseEntity(ex.getMessage(), HttpStatus.NOT_FOUND); } }因此,我们现在可以看到 response code 400 和 404 的文档: 9、使用 @Operation 和 @ApiResponses 生成文档接下来,让我们看看如何使用几个 OpenAPI 专用注解 为我们的 API 添加一些说明。 我们使用 @Operation 和 @ApiResponses 对 controller 的 /api/book/{id} 端点进行注解: @Operation(summary = "Get a book by its id") @ApiResponses(value = { @ApiResponse(responseCode = "200", description = "Found the book", 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()); }效果如下: 我们可以看到,我们添加到 @Operation 中的文本被置于 API 操作层。同样,在 @ApiResponses 容器注解中添加到各种 @ApiResponse 元素中的说明也在这里可见,从而为我们的 API 响应增添了意义。 我们没有为上述 400 和 404 响应定义任何 schema。由于我们为它们定义了一个空 @Content,因此只显示了它们的描述。 11、对 Kotlin 的支持Spring Boot 2.x 起,就为 Kotlin 提供了一流的支持。由于我们使用的是 Spring Boot 3.x 版本,因此 SpringDoc 支持用 Kotlin 编写的应用程序。 我们将在 Kotlin 中创建一个简单的 Foo API,以了解其实际效果。 完成初始设置后,我们将添加一个 data class 和一个 controller。我们将把它们添加到 Boot 应用程序的一个子包中,这样当程序运行时,它就会同时加载我们的 FooController 和之前的 BookController: @Entity data class Foo( @Id val id: Long = 0, @NotBlank @Size(min = 0, max = 50) val name: String = "" ) @RestController @RequestMapping("/") class FooController() { val fooList: List = listOf(Foo(1, "one"), Foo(2, "two")) @Operation(summary = "Get all foos") @ApiResponses(value = [ ApiResponse(responseCode = "200", description = "Found Foos", content = [ (Content(mediaType = "application/json", array = ( ArraySchema(schema = Schema(implementation = Foo::class)))))]), ApiResponse(responseCode = "400", description = "Bad request", content = [Content()]), ApiResponse(responseCode = "404", description = "Did not find any Foos", content = [Content()])] ) @GetMapping("/foo") fun getAllFoos(): List = fooList }现在,当我们点击 API 文档 URL 时,也会看到 Foo API: 为了增强对 Kotlin 类型的支持,我们可以添加此依赖项: org.springdoc springdoc-openapi-starter-common |
今日新闻 |
推荐新闻 |
专题文章 |
CopyRight 2018-2019 实验室设备网 版权所有 |