Spring Boot的OpenAPI 3文档


OpenAPI 3 Documentation With Spring Boot

在本教程中，我们将尝试启用Spring Boot Open API 3的REST项目，并探索其某些功能。 Springdoc-openapi Java库正迅速变得非常引人注目。

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

先决条件：

  • Java8.x。

  • Maven3.x。

    • 脚步

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

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    <?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>
      spring-boot-starter-parent</artifactId>
      <version>2.2.2.RELEASE</version>
      <relativePath ></relativePath> <!-- lookup parent from repository -->
     </parent>
     <groupId>com.example</groupId>
     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>
       spring-boot-starter-web</artifactId>
      </dependency>
      <dependency>
       <groupId>org.springdoc</groupId>
       springdoc-openapi-ui</artifactId>
       <version>1.2.32</version>
      </dependency>
     
      <dependency>
       <groupId>org.springframework.boot</groupId>
       spring-boot-starter-test</artifactId>
       <scope>test</scope>
       <exclusions>
        <exclusion>
         <groupId>org.junit.vintage</groupId>
         junit-vintage-engine</artifactId>
        </exclusion>
       </exclusions>
      </dependency>
     </dependencies>

     <build>
      <plugins>
       <plugin>
        <groupId>org.springframework.boot</groupId>
        spring-boot-maven-plugin</artifactId>
       </plugin>
      </plugins>
     </build>

    </project>

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

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

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
    86
    87
    88
    89
    90
    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的示例。 现在，让我们创建一个控制器。

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    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控制器。

    让我们在 srcmain中输入一些内容
    esourcesapplication.properties     。

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

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

    最后，让我们编写spring boot应用程序类

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    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中的样子：

    Initial project structure

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

    您也可以通过从IDE运行SampleApplication.java类来启动应用程序。

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

    Sample application with Swagger

    点击绿色的发布按钮，并展开 Schemas 下的 Person 右侧的> 符号。

    Schema and response

    妙处是如何利用模型上的JSR-303注释自动详细制定合同。 它开箱即用地涵盖了许多重要的注释并记录了它们。 但是，我目前还没有看到它对现成的@javax.validation.constraints.Email和@org.hibernate.validator.constraints.CreditCardNumber的支持。

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

    Pressing"Try it Out" button

    按下蓝色的执行按钮。

    Pressing Execute button

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

    1
    2
    3
    4
    5
    6
    7
    8
    9
    {
     "id": 0,
     "firstName":"string",
     "lastName":"string",
     "email":"[email protected]",
     "email1":"[email protected]",
     "age": 20,
     "creditCardNumber":"4111111111111111"
    }

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

    Feeding input to request body

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

    Output of execution

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

    1
    2
    3
    4
    5
    <dependency>
     <groupId>org.springdoc</groupId>
     springdoc-openapi-ui</artifactId>
     <version>1.2.32</version>
    </dependency>

    故障排除技巧

  • 确保先决条件。

  • 如果使用Eclipse IDE，我们可能需要在创建所有文件之后对项目进行Maven更新。

  • 在Swagger UI中，如果您无法访问"模式"定义链接，则可能是因为您需要退出"尝试"模式。 单击一个或两个可能显示的"取消"按钮。

    • 源代码在这里：https://github.com/teq-niq/sample/tree/springdoc-openapi-intro.Git克隆URL：https://github.com/teq-niq/sample.git。分支：springdoc -openapi-intro。

    另外，请阅读第二部分，网址为https://dzone.com/articles/doing-more-with-springdoc-openapi。