使用 Spring Boot 的 OpenAPI 3 文档

2021-09-02 10:55:44 浏览数 (1)

在本篇文章中，我们将尝试启用 Spring Boot Open API 3 的 REST 项目并探索它的一些功能。​Springdoc-openapi​ java 库正迅速变得非常引人注目。

我们将参考https://spring.io/guides/gs/rest-service/和https://springdoc.org/。

先决条件：

  • Java 8.x。
  • Maven 3.x。

步骤

首先创建一个 ​Maven JAR​ 项目。下面，您将看到要使用的 ​pom.xml​：

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.2.2.RELEASE</version>
        <relativePath ></relativePath> <!-- lookup parent from repository -->
    </parent>
    <groupId>com.example</groupId>
    <artifactId>sample</artifactId>
    <version>0.0.1</version>
    <name>sample</name>
    <description>Demo project for Spring Boot with 
    openapi 3 documentation</description>
    <properties>
        <java.version>1.8</java.version>
    </properties>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-ui</artifactId>
            <version>1.2.32</version>
        </dependency>
        
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
            <exclusions>
                <exclusion>
                    <groupId>org.junit.vintage</groupId>
                    <artifactId>junit-vintage-engine</artifactId>
                </exclusion>
            </exclusions>
        </dependency>
    </dependencies>
    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build> 
</project>

请注意“​springdoc-openapi-ui​”依赖项和“​springdoc-openapi-maven-plugin​”插件。

现在，让我们创建一个小的 Java bean 类。 

package sample;

import javax.validation.constraints.Email;
import javax.validation.constraints.Max;
import javax.validation.constraints.Min;
import javax.validation.constraints.NotBlank;
import javax.validation.constraints.NotNull;
import javax.validation.constraints.Pattern;
import javax.validation.constraints.Size;
import javax.xml.bind.annotation.XmlAccessType;
import javax.xml.bind.annotation.XmlAccessorType;
import javax.xml.bind.annotation.XmlRootElement;
import org.hibernate.validator.constraints.CreditCardNumber;

@XmlRootElement(name = "person")
@XmlAccessorType(XmlAccessType.FIELD)
public class Person {
    private long id;
    private String firstName;
    @NotNull
    @NotBlank
    private String lastName;
    @Pattern(regexp = ".+@.+\\..+", message = "Please provide a valid email address")
    private String email;
    @Email()
    private String email1;
    @Min(18)
    @Max(30)
    private int age;
    @CreditCardNumber
    private String creditCardNumber;

    public String getCreditCardNumber() {
        return creditCardNumber;
    }
    public void setCreditCardNumber(String creditCardNumber) {
        this.creditCardNumber = creditCardNumber;
    }
    public long getId() {
        return id;
    }
    public void setId(long id) {
        this.id = id;
    }
    public String getEmail1() {
        return email1;
    }
    public void setEmail1(String email1) {
        this.email1 = email1;
    }
    @Size(min = 2)
    public String getFirstName() {
        return firstName;
    }
    public void setFirstName(String firstName) {
        this.firstName = firstName;
    }
    public String getLastName() {
        return lastName;
    }
    public void setLastName(String lastName) {
        this.lastName = lastName;
    }
    public String getEmail() {
        return email;
    }
    public void setEmail(String email) {
        this.email = email;
    }
    public int getAge() {
        return age;
    }
    public void setAge(int age) {
        this.age = age;
    }
}

这是 ​Java bean​ 的一个示例。现在，让我们创建一个控制器。

package sample;

import javax.validation.Valid;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class PersonController {
    @RequestMapping(path = "/person", method = RequestMethod.POST)
    public Person person(@Valid @RequestBody Person person) {
        return person;
    }
}

上面是一个示例 ​REST ​控制器。

application-description=@project.description@
application-version=@project.version@
logging.level.org.springframework.boot.autoconfigure=ERROR

上面的条目会将与 Maven 构建相关的信息传递给 OpenAPI 文档。

最后，我们来编写​spring boot​应用类

package sample;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;

@SpringBootApplication
public class SampleApplication {
    public static void main(String[] args) {
        SpringApplication.run(SampleApplication.class, args);
    }

    @Bean
    public OpenAPI customOpenAPI(@Value("${application-description}") String appDesciption, @Value("${application-version}") String appVersion) {
     return new OpenAPI()
          .info(new Info()
          .title("sample application API")
          .version(appVersion)
          .description(appDesciption)
          .termsOfService("http://swagger.io/terms/")
          .license(new License().name("Apache 2.0").url("http://springdoc.org")));
    }
}

还要注意如何从 ​application.properties​ 中利用 API 版本和描述。

在这个阶段，这是项目在 Eclipse 中的样子：

初始项目结构

以上是项目内容。接下来，​mvn clean package​从命令提示符或终端执行。然后，执行​java -jar target\sample-0.0.1.jar​.

n你还可以通过从 IDE 运行 ​SampleApplication.java​ 类来启动应用程序。

现在，让我们访问 Swagger UI — http://localhost:8080/swagger-ui.html：

使用 Swagger 的示例应用程序

单击绿色的​Post​按钮并展开​Person​右侧​Schemas​下的​>​符号。

架构和响应

好处是如何利用模型上的 JSR-303 注释自动详细说明合同。它开箱即用地涵盖了许多重要的注释并记录了它们。不过，我没有看到它支持开箱​@javax.validation.constraints.Email​，并​@org.hibernate.validator.constraints.CreditCardNumber​在这个时间点。

为了完整起见，让我们发布一个请求。按试用按钮。

按“试用”按钮

按下蓝色的执行按钮。

按执行按钮

让我们输入一个有效的输入：

{
  "id": 0,
  "firstName": "string",
  "lastName": "string",
  "email": "abc@abc.com",
  "email1": "abc@abc.com",
  "age": 20,
  "creditCardNumber": "4111111111111111"
}

让我们将该有效输入输入请求正文部分

向请求正文提供输入

按下蓝色的执行按钮后，我们会看到以下内容：

执行输出

这只是对依赖项功能的简要介绍：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.2.32</version>
</dependency>

故障排除提示

  • 确保先决条件。
  • 如果使用 Eclipse IDE，我们可能需要在创建所有文件后对项目进行 Maven 更新。
  • 在 Swagger UI 中，如果您无法访问“Schema”定义链接，可能是因为您需要退出“try it out”模式。单击一两个可能可见的取消按钮。

本篇关于Spring boot使用Open API 3文档的介绍就到此结束了，感谢各位的阅读。

Java SpringBoot

0 人点赞