App下載

使用 Spring Boot 的 OpenAPI 3 文檔

星河幾重 2021-09-02 10:55:44 瀏覽數(shù) (6746)
反饋

在本篇文章中，我們將嘗試啟用 Spring Boot Open API 3 的 REST 項(xiàng)目并探索它的一些功能。?Springdoc-openapi? java 庫(kù)正迅速變得非常引人注目。

我們將參考https://spring.io/guides/gs/rest-service/和https://springdoc.org/。

先決條件：

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

步驟

首先創(chuàng)建一個(gè) ?Maven JAR? 項(xiàng)目。下面，您將看到要使用的 ?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>

請(qǐng)注意“?springdoc-openapi-ui?”依賴項(xiàng)和“?springdoc-openapi-maven-plugin?”插件。

現(xiàn)在，讓我們創(chuàng)建一個(gè)小的 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? 的一個(gè)示例。現(xiàn)在，讓我們創(chuàng)建一個(gè)控制器。

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;
    }
}

上面是一個(gè)示例 ?REST ?控制器。

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

上面的條目會(huì)將與 Maven 構(gòu)建相關(guān)的信息傳遞給 OpenAPI 文檔。

最后，我們來(lái)編寫?spring boot?應(yīng)用類

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 版本和描述。

在這個(gè)階段，這是項(xiàng)目在 Eclipse 中的樣子：

初始項(xiàng)目結(jié)構(gòu)

以上是項(xiàng)目?jī)?nèi)容。接下來(lái)，?mvn clean package?從命令提示符或終端執(zhí)行。然后，執(zhí)行?java -jar target\sample-0.0.1.jar?.

n你還可以通過(guò)從 IDE 運(yùn)行 ?SampleApplication.java? 類來(lái)啟動(dòng)應(yīng)用程序。

現(xiàn)在，讓我們?cè)L問 Swagger UI — http://localhost:8080/swagger-ui.html：

使用 Swagger 的示例應(yīng)用程序

單擊綠色的?Post?按鈕并展開?Person?右側(cè)?Schemas?下的?>?符號(hào)。

架構(gòu)和響應(yīng)

好處是如何利用模型上的 JSR-303 注釋自動(dòng)詳細(xì)說(shuō)明合同。它開箱即用地涵蓋了許多重要的注釋并記錄了它們。不過(guò)，我沒有看到它支持開箱?@javax.validation.constraints.Email?，并?@org.hibernate.validator.constraints.CreditCardNumber?在這個(gè)時(shí)間點(diǎn)。

為了完整起見，讓我們發(fā)布一個(gè)請(qǐng)求。按試用按鈕。

按“試用”按鈕

按下藍(lán)色的執(zhí)行按鈕。

按執(zhí)行按鈕

讓我們輸入一個(gè)有效的輸入：

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

讓我們將該有效輸入輸入請(qǐng)求正文部分

向請(qǐng)求正文提供輸入

按下藍(lán)色的執(zhí)行按鈕后，我們會(huì)看到以下內(nèi)容：

執(zhí)行輸出

這只是對(duì)依賴項(xiàng)功能的簡(jiǎn)要介紹：

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

故障排除提示

  • 確保先決條件。
  • 如果使用 Eclipse IDE，我們可能需要在創(chuàng)建所有文件后對(duì)項(xiàng)目進(jìn)行 Maven 更新。
  • 在 Swagger UI 中，如果您無(wú)法訪問“Schema”定義鏈接，可能是因?yàn)槟枰顺觥皌ry it out”模式。單擊一兩個(gè)可能可見的取消按鈕。

本篇關(guān)于Spring boot使用Open API 3文檔的介紹就到此結(jié)束了，感謝各位的閱讀。

Java SpringBoot

1 人點(diǎn)贊