index.adoc

Vert.x OpenAPI

Table of Contents

• Using Vert.x OpenAPI
• OpenAPIContract
  • Path, Operation, Parameter
• Validation of Requests
• Validation of Responses
• Handle Validation Exceptions

Vert.x OpenAPI extends Vert.x to support OpenAPI 3 in version 3.0 and 3.1.

Vert.x OpenAPI can:

• parse and validate your OpenAPI contract.

• parse and validate incoming requests according to your OpenAPI contract.

• parse and validate outgoing responses according to your OpenAPI contract.

Using Vert.x OpenAPI

To use Vert.x OpenAPI, add the following dependency to the dependencies section of your build descriptor:

• Maven (in your pom.xml):

<dependency>
  <groupId>io.vertx</groupId>
  <artifactId>vertx-openapi</artifactId>
  <version>${maven.version}</version>
</dependency>

• Gradle (in your build.gradle file):

dependencies {
  compile 'io.vertx:vertx-openapi:${maven.version}'
}

OpenAPIContract

When using Vert.x OpenAPI you always start with creating an instance of {@link io.vertx.openapi.contract.OpenAPIContract} from your contract.

{@link examples.ContractExamples#createContract}

Note	Due to security reasons this library is not downloading external references from your contract. In case your contract requires external resources, they must be downloaded upfront and also provided to the {@link io.vertx.openapi.contract.OpenAPIContract}.

The example below shows a snippet from an example OpenAPI contract that includes a reference to an external resource and how to create an instance of {@link io.vertx.openapi.contract.OpenAPIContract}.

paths:
  /pets:
    get:
      operationId: listPets
      parameters:
        - name: query
          schema:
            $ref: 'https://example.com/pet-components#/components/schemas/Query'

{@link examples.ContractExamples#createContractAdditionalFiles}

Note	During the instantiation of {@link io.vertx.openapi.contract.OpenAPIContract} the contract gets validated. In case your contract does not match the OpenAPI specification or uses features which are not yet supported an error is thrown.

Path, Operation, Parameter

The {@link io.vertx.openapi.contract.OpenAPIContract} interface offers methods to navigate to the {@link io.vertx.openapi.contract.Path}, {@link io.vertx.openapi.contract.Operation} and {@link io.vertx.openapi.contract.Parameter} objects of the OpenAPI contract.

{@link examples.ContractExamples#pathParameterOperationExample}

Validation of Requests

The {@link io.vertx.openapi.validation.RequestValidator} offers multiple validate methods to validate incoming requests.

{@link examples.ValidationExamples#createValidator}

The {@link io.vertx.openapi.validation.RequestValidator} also offers a signature of the validate method that consumes a {@link io.vertx.openapi.validation.ValidatableRequest}.

{@link examples.ValidationExamples#validatableRequest}

Note

The parameters in a {@link io.vertx.openapi.validation.ValidatableRequest} must be stored in a specific format depending on the style, location and if they are exploded or not, otherwise the {@link io.vertx.openapi.validation.RequestValidator} can’t validate the request. The required format MUST exactly look like as described in the JavaDoc of {@link io.vertx.openapi.validation.RequestValidator}.

Validation of Responses

The {@link io.vertx.openapi.validation.ResponseValidator} offers a validate method to validate responses. {@link io.vertx.openapi.validation.ValidatableResponse} offers multiple create methods to build validatable responses easily.

In case that the validation of a response has passed, the returned {@link io.vertx.openapi.validation.ValidatedResponse} can directly be sent back to the client.

{@link examples.ValidationExamples#validatableResponse}

Note

The parameters in a {@link io.vertx.openapi.validation.ValidatableResponse} must be stored in a specific format depending on the style, location and if they are exploded or not, otherwise the {@link io.vertx.openapi.validation.ResponseValidator} can’t validate the response. The required format MUST exactly look like as described in the JavaDoc of {@link io.vertx.openapi.validation.ResponseValidator}.

Handle Validation Exceptions

A {@link io.vertx.openapi.validation.ValidatorException} is thrown, if the validation of a request or response fails. The validation can fail for formal reasons, such as the wrong format for a parameter or the absence of a required parameter. However, validation can of course also fail because the content does not match the defined schema. In this case a {@link io.vertx.openapi.validation.SchemaValidationException} is thrown. It is a subclass of ValidatorException and provides access to the related {@link io.vertx.json.schema.OutputUnit} to allow further analysis of the error.