add vertx-openapi example

openapi-examples/README.adoc

@@ -0,0 +1,9 @@
+= Vert.x JUnit 5 examples
+
+This project illustrates how to use https://vertx.io/docs/vertx-openapi/java/[Vert.x OpenAPI] for validating incoming requests.
+
+The link:src/test/java/io/vertx/example/openapi/CreateContract.java[CreateContract.java] file contains examples to explain how an OpenAPIContract class can be instantiated.
+
+The link:src/test/java/io/vertx/example/openapi/ValidateRequest.java[ValidateRequest.java] file contains examples to explain how an incoming request can be validated against an OpenAPIContract.
+
+It is highly recommended to also check the https://vertx.io/docs/vertx-web-openapi-router/java/[Vert.x OpenAPI Router], in case you haven't heard about it yet.

openapi-examples/pom.xml

@@ -0,0 +1,84 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  ~ Copyright (c) 2018 Red Hat, Inc.
+  ~
+  ~ Licensed under the Apache License, Version 2.0 (the "License");
+  ~ you may not use this file except in compliance with the License.
+  ~ You may obtain a copy of the License at
+  ~
+  ~     http://www.apache.org/licenses/LICENSE-2.0
+  ~
+  ~ Unless required by applicable law or agreed to in writing, software
+  ~ distributed under the License is distributed on an "AS IS" BASIS,
+  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  ~ See the License for the specific language governing permissions and
+  ~ limitations under the License.
+  -->
+
+<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 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+
+  <groupId>io.vertx</groupId>
+  <artifactId>openapi-examples</artifactId>
+  <version>4.5.8</version>
+
+  <properties>
+    <maven-surefire-plugin.version>2.22.2</maven-surefire-plugin.version>
+  </properties>
+
+  <dependencyManagement>
+    <dependencies>
+      <dependency>
+        <groupId>io.vertx</groupId>
+        <artifactId>vertx-stack-depchain</artifactId>
+        <version>${project.version}</version>
+        <type>pom</type>
+        <scope>import</scope>
+      </dependency>
+    </dependencies>
+  </dependencyManagement>
+
+  <dependencies>
+
+    <dependency>
+      <groupId>io.vertx</groupId>
+      <artifactId>vertx-openapi</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>io.vertx</groupId>
+      <artifactId>vertx-web-client</artifactId>
+    </dependency>
+  </dependencies>
+
+  <build>
+    <plugins>
+      <plugin>
+        <artifactId>maven-compiler-plugin</artifactId>
+        <version>3.1</version>
+        <configuration>
+          <source>11</source>
+          <target>11</target>
+        </configuration>
+      </plugin>
+      <plugin>
+        <artifactId>maven-surefire-plugin</artifactId>
+        <version>${maven-surefire-plugin.version}</version>
+      </plugin>
+    </plugins>
+  </build>
+
+  <profiles>
+    <profile>
+      <id>staging</id>
+      <repositories>
+        <repository>
+          <id>staging</id>
+          <url>https://oss.sonatype.org/content/repositories/iovertx-3905/</url>
+        </repository>
+      </repositories>
+    </profile>
+  </profiles>
+
+</project>

openapi-examples/src/main/java/io/vertx/example/openapi/CreateContract.java

@@ -0,0 +1,63 @@
+/*
+ * Copyright (c) 2024, SAP SE
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
+ * which is available at https://www.apache.org/licenses/LICENSE-2.0.
+ *
+ * SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
+ *
+ */
+
+package io.vertx.example.openapi;
+
+
+import io.vertx.core.Vertx;
+import io.vertx.core.Future;
+import io.vertx.openapi.contract.OpenAPIContract;
+
+import java.nio.file.Path;
+import java.util.Map;
+
+public class CreateContract {
+  private static final Path RESOURCES = Path.of("openapi-examples/src/main/resources").toAbsolutePath();
+
+  public static Future<OpenAPIContract> createContract(Vertx vertx) {
+    return OpenAPIContract.from(vertx, RESOURCES.resolve("petstore.yaml").toString());
+  }
+
+  public static Future<OpenAPIContract> createContractAdditionalFiles(Vertx vertx) {
+    Path additionalFilesDir = RESOURCES.resolve("additional_files");
+    String petstore = additionalFilesDir.resolve("petstore.yaml").toString();
+
+    Map<String, String> additionalFiles = Map.of(
+      "https://example.com/petstore", additionalFilesDir.resolve("components.yaml").toString()
+    );
+
+    return OpenAPIContract.from(vertx, petstore, additionalFiles);
+  }
+
+  public static void main(String[] args) {
+    Vertx vertx = Vertx.vertx();
+
+    createContract(vertx).compose(contract -> {
+      System.out.println("Contract created");
+      printContract(contract);
+
+      return createContractAdditionalFiles(vertx);
+    }).onSuccess(contract -> {
+      System.out.println("Contract with additional files created");
+      printContract(contract);
+
+      System.exit(0);
+    }).onFailure(t -> {
+      t.printStackTrace();
+      System.exit(1);
+    });
+  }
+
+  private static void printContract(OpenAPIContract contract) {
+    contract.getPaths().forEach(path -> System.out.println("Path: " + path));
+  }
+}

openapi-examples/src/main/java/io/vertx/example/openapi/ValidateRequest.java

@@ -0,0 +1,38 @@
+/*
+ * Copyright (c) 2024, SAP SE
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
+ * which is available at https://www.apache.org/licenses/LICENSE-2.0.
+ *
+ * SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
+ *
+ */
+
+package io.vertx.example.openapi;
+
+import io.vertx.core.Vertx;
+import io.vertx.openapi.validation.RequestValidator;
+
+public class ValidateRequest {
+
+  public static void main(String[] args) {
+    Vertx vertx = Vertx.vertx();
+
+    CreateContract.createContract(vertx).map(openAPIContract -> RequestValidator.create(vertx, openAPIContract))
+      .onSuccess(requestValidator -> {
+        System.out.println("RequestValidator created");
+        vertx.createHttpServer().requestHandler(req ->
+          requestValidator.validate(req).onFailure(t -> {
+            System.out.println("Request is invalid: " + t.getMessage());
+            req.response().setStatusCode(400).end(t.getMessage());
+          }).onSuccess(validatedRequest -> System.out.println("Request is valid"))
+        ).listen(8080, "localhost");
+        System.out.println("HttpServer created");
+      }).onFailure(t -> {
+        t.printStackTrace();
+        System.exit(1);
+      });
+  }
+}

openapi-examples/src/main/resources/additional_files/components.yaml

@@ -0,0 +1,33 @@
+openapi: 3.1.0
+info:
+  version: 1.0.0
+  title: Swagger Petstore
+  license:
+    identifier: MIT
+    name: MIT License
+components:
+  schemas:
+    Pet:
+      type: object
+      required:
+        - id
+        - name
+      properties:
+        id:
+          type: integer
+          format: int64
+        name:
+          type: string
+        tag:
+          type: string
+    Error:
+      type: object
+      required:
+        - code
+        - message
+      properties:
+        code:
+          type: integer
+          format: int32
+        message:
+          type: string

openapi-examples/src/main/resources/additional_files/petstore.yaml

@@ -0,0 +1,32 @@
+openapi: 3.1.0
+info:
+  version: 1.0.0
+  title: Swagger Petstore
+  license:
+    identifier: MIT
+    name: MIT License
+servers:
+  - url: https://petstore.swagger.io/v1
+security:
+  - BasicAuth: []
+paths:
+  /pets:
+    post:
+      summary: Create a pet
+      operationId: createPets
+      tags:
+        - pets
+      requestBody:
+        description: Create a new pet in the store
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: https://example.com/petstore#/components/schemas/Pet
+      responses:
+        default:
+          description: unexpected error
+          content:
+            application/json:
+              schema:
+                $ref: https://example.com/petstore#/components/schemas/Error

openapi-examples/src/main/resources/petstore.yaml

@@ -0,0 +1,116 @@
+openapi: 3.0.0
+info:
+  version: 1.0.0
+  title: Swagger Petstore
+  license:
+    name: MIT
+servers:
+  - url: http://petstore.swagger.io/v1
+paths:
+  /pets:
+    get:
+      summary: List all pets
+      operationId: listPets
+      tags:
+        - pets
+      parameters:
+        - name: limit
+          in: query
+          description: How many items to return at one time (max 100)
+          required: false
+          schema:
+            type: integer
+            format: int32
+      responses:
+        200:
+          description: An paged array of pets
+          headers:
+            x-next:
+              description: A link to the next page of responses
+              schema:
+                type: string
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Pets"
+        default:
+          description: unexpected error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+    post:
+      summary: Create a pet
+      operationId: createPets
+      tags:
+        - pets
+      requestBody:
+        content:
+          "application/json":
+            schema:
+              $ref: "#/components/schemas/Pet"
+      responses:
+        201:
+          description: Null response
+        default:
+          description: unexpected error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+  /pets/{petId}:
+    get:
+      summary: Info for a specific pet
+      operationId: showPetById
+      tags:
+        - pets
+      parameters:
+        - name: petId
+          in: path
+          required: true
+          description: The id of the pet to retrieve
+          schema:
+            type: string
+      responses:
+        200:
+          description: Expected response to a valid request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Pets"
+        default:
+          description: unexpected error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+components:
+  schemas:
+    Pet:
+      type: object
+      required:
+        - id
+        - name
+      properties:
+        id:
+          type: integer
+          format: int64
+        name:
+          type: string
+        tag:
+          type: string
+    Pets:
+      type: array
+      items:
+        $ref: "#/components/schemas/Pet"
+    Error:
+      type: object
+      required:
+        - code
+        - message
+      properties:
+        code:
+          type: integer
+          format: int32
+        message:
+          type: string