Spring Boot: Spring Doc生成OpenAPI3.0文檔

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 依賴到 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 領取翻譯文章福利：