1.概述
文檔是構建REST API的重要組成部分。在本文中，我們將瞭解一下SpringDoc。這是一個基於OpenAPI 3.0規範針對Spring Boot 1.x和2.x應用程序簡化API文檔生成和維護的工具。
2.設置springdoc-openapi
為了讓springdoc-openapi自動為我們的API生成OpenAPI 3規範文檔，我們只需將springdoc-openapi-ui依賴項添加到我們的pom.xml中：
<code><dependency>
<groupid>org.springdoc/<groupid>
<artifactid>springdoc-openapi-ui/<artifactid>
<version>1.2.32/<version>
/<dependency>/<code>
然後，當我們運行我們的應用程序時，默認情況下，OpenAPI描述將在路徑/ v3 / api-docs中可用-例如：
<code>http://localhost:8080/v3/api-docs//<code>
要使用定製路徑，我們可以在application.properties文件中指出：
<code>springdoc.api-docs.path=/api-docs/<code>
現在，我們可以在以下位置訪問文檔：
<code>http://localhost:8080/api-docs//<code>
默認情況下，OpenAPI定義為JSON 格式。對於yaml格式，我們可以在以下位置獲取定義：
<code>http://localhost:8080/api-docs.yaml/<code>
3.使用Swagger UI設置springdoc-openapi
除了自己生成OpenAPI 3規範外，我們還可以將springdoc-openapi與Swagger UI集成在一起，以便我們可以與API規範進行交互並執行端點。
3.1 Maven依賴
要使用Swagger UI設置springdoc-openapi，我們要做的就是將依賴項springdoc-openapi-ui添加到項目的pom.xml中：
<code><dependency>
<groupid>org.springdoc/<groupid>
<artifactid>springdoc-openapi-ui/<artifactid>
<version>1.2.32/<version>
/<dependency>/<code>
現在，我們可以在以下位置訪問API文檔：
<code>http://localhost:8080/swagger-ui.html/<code>
我們可以通過添加屬性來自定義路徑：
<code>springdoc.swagger-ui.path=/swagger-ui-custom.html/<code>
3.2 樣本API
假設我們的應用程序具有一個用於管理Book的控制器：
<code>@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<book> findBooks() {
return repository.getBooks();
}
@PutMapping("/{id}")
@ResponseStatus(HttpStatus.OK)
public Book updateBook(@PathVariable("id") final String id, @RequestBody final Book book) {
return book;
}
}/<book>/<code>
然後，當我們運行應用程序時，可以在以下位置查看文檔：
<code>http://localhost:8080/swagger-ui-custom.html/<code>
深入到/ api / book端點，並查看其請求和響應的詳細信息：
4.將springdoc-openapi與Spring WebFlux集成
我們可以通過添加springdoc-openapi-webflux-ui將springdoc-openapi和Swagger UI集成到Spring WebFlux項目中：
<code><dependency>
<groupid>org.springdoc/<groupid>
<artifactid>springdoc-openapi-webflux-ui/<artifactid>
<version>1.2.32/<version>
/<dependency>/<code>
而且，像以前一樣，可以在以下位置訪問該文檔：
<code>http://localhost:8080/swagger-ui.html/<code>
同樣，我們可以在application.properties文件中添加springdoc.swagger-ui.path屬性以自定義路徑。
5.公開分頁信息
Spring Data JPA與Spring MVC無縫集成，此類集成的一個示例是 Pageable 支持：
<code>@GetMapping("/filter")
public Page<book> filterBooks(Pageable pageable) {
return repository.getBooks(pageable);
}/<book>/<code>最初，我們可能希望SpringDoc 在生成的文檔中添加 page，size和sort查詢參數。但是，默認情況下，SpringDoc不滿足此期望。為了解鎖此功能，我們應該添加springdoc-openapi-data-rest 依賴項：
<code><dependency>
<groupid>org.springdoc/<groupid>
<artifactid>springdoc-openapi-data-rest/<artifactid>
<version>1.2.32/<version>
/<dependency>/<code>
現在，它將預期的查詢參數添加到文檔中：
6.使用springdoc-openapi Maven插件
springdoc-openapi庫提供了一個Maven插件springdoc-openapi-maven-plugin，用於生成json和yaml格式的OpenAPI描述。
該springdoc-的OpenAPI，Maven的插件使用該插件彈簧啟動的Maven插件。Maven 在集成測試階段運行 openapi插件。
讓我們看看如何在pom.xml中配置插件：
<code><plugin>
<groupid>org.springframework.boot/<groupid>
<artifactid>spring-boot-maven-plugin/<artifactid>
<version>2.1.8.RELEASE/<version>
<executions>
<execution>
pre-integration-test
<goals>
<goal>start/<goal>
/<goals>
/<execution>
<execution>
post-integration-test
<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>/<code>
另外，我們可以配置插件以使用自定義值：
<code><plugin>
<executions>
.........
/<executions>
<configuration>
<apidocsurl>http://localhost:8080/v3/api-docs/<apidocsurl>
<outputfilename>openapi.json/<outputfilename>
<outputdir>${project.build.directory}/<outputdir>
/<configuration>
/<plugin>/<code>
讓我們仔細看看我們可以為插件配置的參數：
- apiDocsUrl –可以使用JSON格式訪問文檔的URL，默認為http：// localhost：8080 / v3 / api-docs
- outputFileName –存儲定義的文件的名稱，默認為openapi.json
- outputDir –文檔存儲目錄的絕對路徑–默認情況下，$ {project.build.directory}
7.使用JSR-303 Bean驗證自動生成文檔
當我們的模型包括JSR-303 Bean驗證註釋，比如 @NotNull，@NotBlank，@Size，@Min和@Max的springdoc-OpenAPI的庫使用它們來生成相應的約束其他架構文檔。
讓我們來看一個使用Book Bean 的示例：
<code>public class Book {
private long id;
@NotBlank
@Size(min = 0, max = 20)
private String title;
@NotBlank
@Size(min = 0, max = 30)
private String author;
}/<code>現在，為Book bean 生成的文檔提供了更多信息：
8.使用@ControllerAdvice和@ResponseStatus生成文檔
使用@ResponseStatus在一個方法@RestControllerAdvice類會自動生成用於響應代碼的文檔。在此@RestControllerAdvice類中，這兩種方法都使用@ResponseStatus進行註釋：
<code>@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(BookNotFoundException.class)
@ResponseStatus(HttpStatus.NOT_FOUND)
public ResponseEntity<string> handleBookNotFound(RuntimeException ex) {
return new ResponseEntity<>(ex.getMessage(), HttpStatus.NOT_FOUND);
}
}/<string>/<string>/<code>
而且，我們現在將看到響應代碼400和404的文檔：
9.結論
在本文中，我們探討了在項目中設置springdoc-openapi的過程。然後，我們看到了如何將springdoc-openapi與Swagger UI集成在一起。我們還看到了如何使用Spring Webflux項目來做到這一點。
接下來，我們使用springdoc-openapi Maven插件為我們的API生成OpenAPI定義，並且我們瞭解瞭如何從Spring Data中公開分頁和排序信息。最後，我們研究了springdoc-openapi如何使用@ControllerAdvice類中的JSR 303 bean驗證註釋和@ResponseStatus註釋自動生成文檔。
springdoc-openapi根據OpenAPI 3規範生成API文檔，它為我們處理Swagger UI配置，從而使API文檔生成成為一個相當簡單的任務。
讀者福利
分享一份整理好的Java學習資料，裡面包含了：分佈式架構、高可擴展、高性能、高併發、Jvm性能調優、Spring，MyBatis，Nginx源碼分析，Redis，ActiveMQ、、Mycat、Netty、Kafka、Mysql、Zookeeper、Tomcat、Docker、Dubbo、Nginx等多個知識點高級進階乾貨
資料領取方式：關注+轉發，私信回覆“資料”，即可免費領取學習資料。
閱讀更多 java架構北風 的文章
