1. 概述
公司正好最近在整理項目的文檔，且文檔對於構建REST API來說是至關重要的。在這篇文章中，我將介紹Spring Doc ， 一個基於OpenAPI 3規范簡化了Spring Boot 1.x和2.x應用程序的API文檔的生成和維護的工具。
2. 設置springdoc-openapi
如果想讓 springdoc-openapi 為我們的API生成標准的 OpenAPI 3 文檔, 只需要添加 [springdoc-openapi-core](https://search.maven.org/search?q=g:org.springdoc AND a:springdoc-openapi-core&core=gav) 依賴到 pom.xml:
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-core</artifactId>
<version>1.1.45</version>
</dependency>
添加完成后，啟動應用程序，即可訪問默認路徑 /v3/api-docs 查看文檔，如下所示：
http://localhost:8080/v3/api-docs/
如果想要自定義路徑，可在 application.properties 文件中指定 :
springdoc.api-docs.path=/api-docs
這樣，文檔的訪問路徑就變成 :
http://localhost:8080/api-docs/
OpenAPI 默認定義為JSON 格式。對於 yaml 格式，可以訪問下面的路徑獲取 :
http://localhost:8080/api-docs.yaml
3.整合springdoc-openapi 和Swagger UI
除了自己生成OpenAPI 3規范外，我們還可以將springdoc-openapi與Swagger UI集成在一起，以便可以與我們的API規范進行交互並測試端點。
3.1. Maven 依賴
要整合springdoc-openapi 和 Swagger UI ， 唯一要做的就是添加springdoc-openapi-ui依賴到項目pom.xml文件中。
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId>
<version>1.1.45</version>
</dependency>
訪問swagger-ui頁面：
http://localhost:8080/swagger-ui.html
當然也可以像上面一樣，自定義訪問路徑：
springdoc.swagger-ui.path=/swagger-ui-custom.html
3.2. 舉個栗子
假設有個球（國足令人傷心，所以需要個球啊！！）的controller。
@RestController
@RequestMapping("/api/ball")
public class BallController {
@Autowired
private BallRepository repository;
@GetMapping("/{id}")
public Ball findById(@PathVariable long id) {
return repository.findById(id)
.orElseThrow(() -> new BallNotFoundException());
}
@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;
}
}
啟動項目，在瀏覽器中訪問地址：
http://localhost:8080/swagger-ui-custom.html
swagger-ui的界面：
4. springdoc-openapi 與Spring WebFlux集成
我們可以在Spring WebFlux 項目中通過添加依賴：springdoc-openapi-webflux-ui與springdoc-openapi and Swagger UI 集成：
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-webflux-ui</artifactId>
<version>1.1.45</version>
</dependency>
然后，瀏覽器訪問地址
http://localhost:8080/swagger-ui.html
同樣的,可以通過添加 springdoc.swagger-ui.path 配置項到 application.properties文件來自定義文檔訪問路徑。
5. 使用springdoc-openapi Maven 插件
springdoc-openapi 庫提供了 springdoc-openapi-maven-plugin插件，用來生成JSON或者yaml格式的Open API 描述。
springdoc-openapi-maven-plugin 依賴於 spring-boot-maven 插件. Maven在集成測試階段運行openapi插件。
那么，如何在pom.xml中配置插件呢？請看下面的代碼：
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<version>2.1.8.RELEASE</version>
<executions>
<execution>
<id>pre-integration-test</id>
<goals>
<goal>start</goal>
</goals>
</execution>
<execution>
<id>post-integration-test</id>
<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>
當然, 也可以用自定義值來配置插件:
<plugin>
<executions>
.........
</executions>
<configuration>
<apiDocsUrl>http://localhost:8080/v3/api-docs</apiDocsUrl>
<outputFileName>openapi.json</outputFileName>
<outputDir>${project.build.directory}</outputDir>
</configuration>
</plugin>
仔細看看我們在插件中配置的幾個參數：
- apiDocsUrl – 訪問json格式文檔的URL， 默認路徑：http://localhost:8080/v3/api-docs
- outputFileName – 存放定義的路徑, 默認為： openapi.json
- outputDir – 文檔存放的絕對路徑–默認為： ${project.build.directory}
6. 使用 JSR-303 Bean Validation 自動生成文檔
當我們在模型中使用 JSR-303 bean validation 注解, 諸如 @NotNull, @NotBlank, @Size, @Min, @Max等, springdoc-openapi 會為這些bean生成相應的約束。
舉個栗子:
public class Ball {
private long id;
@NotBlank
@Size(min = 0, max = 20)
private String title;
@NotBlank
@Size(min = 0, max = 30)
private String author;
}
為Ball bean生成的文檔內容更為豐富:
7. 使用 @ControllerAdvice和@ResponseStatus生成文檔
在@RestControllerAdvice注解的類中，在方法上使用@ResponseStatus會自動生成帶有返回狀態碼的文檔。如以下被@ControllerAdvice注解的類中，@ResponseStatus修飾的兩個方法:
@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(BallNotFoundException.class)
@ResponseStatus(HttpStatus.NOT_FOUND)
public ResponseEntity<String> handleBallNotFound(RuntimeException ex) {
return new ResponseEntity<>(ex.getMessage(), HttpStatus.NOT_FOUND);
}
}
現在我們可以在文檔中看到返回狀態碼為400和404。
8. 小結
Spring Boot 2.2.x版本目前可能不支持，因此使用時最好使用2.1.x ，本文所使用Spring Boot版本 2.1.8.RELEASE。
以上代碼可在我的github中找到， over on GitHub.
關注公眾號： 回復666 領取翻譯文章福利：
