io.vertx.ext.web.api.contract.openapi3

## Interface OpenAPI3RouterFactory

- All Superinterfaces:
    RouterFactory<io.swagger.v3.oas.models.OpenAPI>

      public interface OpenAPI3RouterFactory
      extends RouterFactory<io.swagger.v3.oas.models.OpenAPI>

  Interface for OpenAPI3RouterFactory.
  To add an handler, use `addHandlerByOperationId(String, Handler)`
  Usage example:

       OpenAPI3RouterFactory.create(vertx, "src/resources/spec.yaml", asyncResult -> {
        if (!asyncResult.succeeded()) {
           // IO failure or spec invalid
        } else {
           OpenAPI3RouterFactory routerFactory = asyncResult.result();
           routerFactory.addHandlerByOperationId("operation_id", routingContext -> {
              // Do something
           }, routingContext -> {
              // Do something with failure handler
           });
           Router router = routerFactory.getRouter();
        }
       });

  Handlers are loaded in this order:
  1. Body handler (Customizable with `this#setBodyHandler(BodyHandler)`
  2. Custom global handlers configurable with `this#addGlobalHandler(Handler)`
  3. Global security handlers defined in upper spec level
  4. Operation specific security handlers
  5. Generated validation handler
  6. User handlers or "Not implemented" handler
  Author:
    Francesco Guardiani @slinkydeveloper

- - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method and Description
    --- | ---
    `OpenAPI3RouterFactory` | `addFailureHandlerByOperationId(String operationId, Handler<RoutingContext> failureHandler)` Add a failure handler by operation_id field in Operation object
    `OpenAPI3RouterFactory` | `addHandlerByOperationId(String operationId, Handler<RoutingContext> handler)` Add an handler by operation_id field in Operation object
    `OpenAPI3RouterFactory` | `addSecuritySchemaScopeValidator(String securitySchemaName, String scopeName, Handler<RoutingContext> handler)` Add a particular scope validator.
    `static void` | `create(Vertx vertx, String url, Handler<AsyncResult<OpenAPI3RouterFactory>> handler)` Create a new OpenAPI3RouterFactory
    `static void` | `create(Vertx vertx, String url, List<JsonObject> auth, Handler<AsyncResult<OpenAPI3RouterFactory>> handler)` Create a new OpenAPI3RouterFactory
    `OpenAPI3RouterFactory` | `mountOperationToEventBus(String operationId, String address)` Specify to route an incoming request for specified operation id to a Web Api Service mounted at the specified address on event bus.
    `OpenAPI3RouterFactory` | `mountServiceFromTag(String tag, String address)` Specify to route an incoming request for all operations that contains the specified tag to a Web Api Service mounted at the specified address on event bus.
    `OpenAPI3RouterFactory` | `mountServiceInterface(Class interfaceClass, String address)` Introspect the Web Api Service interface to route to service all matching method names with operation ids.
    `OpenAPI3RouterFactory` | `mountServicesFromExtensions()` Introspect the OpenAPI spec to mount handlers for all operations that specifies a x-vertx-event-bus annotation.

    - ### Methods inherited from interface io.vertx.ext.web.api.contract.RouterFactory

      `addGlobalHandler, addSecurityHandler, getOptions, getRouter, getValidationFailureHandler, setBodyHandler, setExtraOperationContextPayloadMapper, setNotImplementedFailureHandler, setOptions, setValidationFailureHandler`

- - ### Method Detail

    - #### addSecuritySchemaScopeValidator

          OpenAPI3RouterFactory addSecuritySchemaScopeValidator(String securitySchemaName,
                                                                String scopeName,
                                                                Handler<RoutingContext> handler)

      Add a particular scope validator. The main security schema will not be called if a specific scope validator is configured
      Parameters:
        `securitySchemaName` -
        `scopeName` -
        `handler` -
      Returns:
        this factory

    - #### addHandlerByOperationId

          OpenAPI3RouterFactory addHandlerByOperationId(String operationId,
                                                        Handler<RoutingContext> handler)

      Add an handler by operation_id field in Operation object
      Parameters:
        `operationId` -
        `handler` -
      Returns:
        this factory

    - #### addFailureHandlerByOperationId

          OpenAPI3RouterFactory addFailureHandlerByOperationId(String operationId,
                                                               Handler<RoutingContext> failureHandler)

      Add a failure handler by operation_id field in Operation object
      Parameters:
        `operationId` -
        `failureHandler` -
      Returns:
        this factory

    - #### mountOperationToEventBus

          OpenAPI3RouterFactory mountOperationToEventBus(String operationId,
                                                         String address)

      Specify to route an incoming request for specified operation id to a Web Api Service mounted at the specified address on event bus. Please give a look at vertx-web-api-service documentation for more informations
      Parameters:
        `operationId` -
        `address` -
      Returns:
        this factory

    - #### mountServiceFromTag

          OpenAPI3RouterFactory mountServiceFromTag(String tag,
                                                    String address)

      Specify to route an incoming request for all operations that contains the specified tag to a Web Api Service mounted at the specified address on event bus. The request is handled by the method that matches the operation id. Please give a look at vertx-web-api-service documentation for more informations
      Parameters:
        `tag` -
        `address` -
      Returns:
        this factory

    - #### mountServicesFromExtensions

          OpenAPI3RouterFactory mountServicesFromExtensions()

      Introspect the OpenAPI spec to mount handlers for all operations that specifies a x-vertx-event-bus annotation. Please give a look at vertx-web-api-service documentation for more informations
      Returns:
        this factory

    - #### mountServiceInterface

          OpenAPI3RouterFactory mountServiceInterface(Class interfaceClass,
                                                      String address)

      Introspect the Web Api Service interface to route to service all matching method names with operation ids. Please give a look at vertx-web-api-service documentation for more informations
      Returns:
        this factory

    - #### create

          static void create(Vertx vertx,
                             String url,
                             Handler<AsyncResult<OpenAPI3RouterFactory>> handler)

      Create a new OpenAPI3RouterFactory
      Parameters:
        `vertx` -
        `url` - location of your spec. It can be an absolute path, a local path or remote url (with HTTP protocol)
        `handler` - When specification is loaded, this handler will be called with AsyncResult

    - #### create

          static void create(Vertx vertx,
                             String url,
                             List<JsonObject> auth,
                             Handler<AsyncResult<OpenAPI3RouterFactory>> handler)

      Create a new OpenAPI3RouterFactory
      Parameters:
        `vertx` -
        `url` - location of your spec. It can be an absolute path, a local path or remote url (with HTTP protocol)
        `auth` - list of authorization values needed to access the remote url. Each item should be json representation of an `AuthorizationValue`
        `handler` - When specification is loaded, this handler will be called with AsyncResult

Copyright © 2021 Eclipse. All rights reserved.