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

1. 概述

公司正好最近在整理项目的文档，且文档对于构建rest api来说是至关重要的。在这篇文章中，我将介绍spring doc ， 一个基于openapi 3规范简化了spring boot 1.x和2.x应用程序的api文档的生成和维护的工具。

2. 设置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 领取翻译文章福利：