使用 Spring Boot 的 OpenAPI 3 文档

2023-03-07 14:57| 来源: 网络整理| 查看: 265

在本篇文章中，我们将尝试启用 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：

4.0.0 org.springframework.boot spring-boot-starter-parent 2.2.2.RELEASE com.example sample 0.0.1 sample Demo project for Spring Boot with openapi 3 documentation 1.8 org.springframework.boot spring-boot-starter-web org.springdoc springdoc-openapi-ui 1.2.32 org.springframework.boot spring-boot-starter-test test org.junit.vintage junit-vintage-engine org.springframework.boot spring-boot-maven-plugin

请注意“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 控制器。

[email protected]@ [email protected]@ 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": "[email protected]", "email1": "[email protected]", "age": 20, "creditCardNumber": "4111111111111111" }

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

向请求正文提供输入

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

执行输出

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

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

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

【本文地址】

公司简介

联系我们