io.vertx.ext.web.openapi

## Interface RouterBuilder

-     public interface RouterBuilder

  Interface to build a Vert.x Web `Router` from an OpenAPI 3 contract.
  To add an handler, use `operation(String)` (String, Handler)}
  Usage example:

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

  Handlers are loaded in this order:
  1. Body handler (Customizable with `this#bodyHandler(BodyHandler)`
  2. Custom global handlers configurable with `this#rootHandler(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
    --- | ---
    `RouterBuilder` | `bodyHandler(BodyHandler bodyHandler)` Supply your own BodyHandler if you would like to control body limit, uploads directory and deletion of uploaded files.
    `static Future<RouterBuilder>` | `create(Vertx vertx, String url)` Create a new `RouterBuilder`
    `static void` | `create(Vertx vertx, String url, Handler<AsyncResult<RouterBuilder>> handler)` Like `this#create(Vertx, String)`
    `static Future<RouterBuilder>` | `create(Vertx vertx, String url, OpenAPILoaderOptions options)` Create a new `RouterBuilder`
    `static void` | `create(Vertx vertx, String url, OpenAPILoaderOptions options, Handler<AsyncResult<RouterBuilder>> handler)` Like `this#create(Vertx, String, OpenAPILoaderOptions)`
    `Router` | `createRouter()` Construct a new router based on spec.
    `OpenAPIHolder` | `getOpenAPI()`
    `RouterBuilderOptions` | `getOptions()`
    `SchemaParser` | `getSchemaParser()`
    `SchemaRouter` | `getSchemaRouter()`
    `RouterBuilder` | `mountServiceInterface(Class interfaceClass, String address)` Introspect the Web Api Service interface to route to service all matching method names with operation ids.
    `RouterBuilder` | `mountServicesFromExtensions()` Introspect the OpenAPI spec to mount handlers for all operations that specifies a x-vertx-event-bus annotation.
    `Operation` | `operation(String operationId)` Access to an operation defined in the contract with `operationId`
    `List<Operation>` | `operations()`
    `RouterBuilder` | `rootHandler(Handler<RoutingContext> rootHandler)` Add global handler to be applied prior to `Router` being generated.
    `RouterBuilder` | `securityHandler(String securitySchemaName, AuthenticationHandler handler)` Mount to paths that have to follow a security schema a security handler
    `RouterBuilder` | `serviceExtraPayloadMapper(java.util.function.Function<RoutingContext,JsonObject> serviceExtraPayloadMapper)` When set, this function is called while creating the payload of `ServiceRequest`
    `RouterBuilder` | `setOptions(RouterBuilderOptions options)` Set options of router builder.

- - ### Method Detail

    - #### operation

          Operation operation(String operationId)

      Access to an operation defined in the contract with `operationId`
      Parameters:
        `operationId` - the id of the operation
      Returns:
        the requested operation
      Throws:
        `IllegalArgumentException` - if the operation id doesn't exist in the contract

    - #### operations

          List<Operation> operations()

      Returns:
        all operations defined in the contract

    - #### bodyHandler

          RouterBuilder bodyHandler(BodyHandler bodyHandler)

      Supply your own BodyHandler if you would like to control body limit, uploads directory and deletion of uploaded files. If you provide a null body handler, you won't be able to validate request bodies
      Parameters:
        `bodyHandler` -
      Returns:
        self

    - #### rootHandler

          RouterBuilder rootHandler(Handler<RoutingContext> rootHandler)

      Add global handler to be applied prior to `Router` being generated.
      Please note that you should not add a body handler inside that list. If you want to modify the body handler, please use `bodyHandler(BodyHandler)`
      Parameters:
        `rootHandler` -
      Returns:
        self

    - #### securityHandler

          RouterBuilder securityHandler(String securitySchemaName,
                                        AuthenticationHandler handler)

      Mount to paths that have to follow a security schema a security handler
      Parameters:
        `securitySchemaName` -
        `handler` -
      Returns:
        self

    - #### mountServicesFromExtensions

          RouterBuilder 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:
        self

    - #### mountServiceInterface

          RouterBuilder 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:
        self

    - #### setOptions

          RouterBuilder setOptions(RouterBuilderOptions options)

      Set options of router builder. For more info `RouterBuilderOptions`
      Parameters:
        `options` -
      Returns:
        self

    - #### getOptions

          RouterBuilderOptions getOptions()

      Returns:
        options of router builder. For more info `RouterBuilderOptions`

    - #### getOpenAPI

          OpenAPIHolder getOpenAPI()

      Returns:
        holder used by self to process the OpenAPI. You can use it to resolve `$ref`s

    - #### getSchemaRouter

          SchemaRouter getSchemaRouter()

      Returns:
        schema router used by self to internally manage all `Schema` instances

    - #### getSchemaParser

          SchemaParser getSchemaParser()

      Returns:
        schema parser used by self to parse all `Schema`

    - #### serviceExtraPayloadMapper

          RouterBuilder serviceExtraPayloadMapper(java.util.function.Function<RoutingContext,JsonObject> serviceExtraPayloadMapper)

      When set, this function is called while creating the payload of `ServiceRequest`
      Parameters:
        `serviceExtraPayloadMapper` -
      Returns:
        self

    - #### createRouter

          Router createRouter()

      Construct a new router based on spec. It will fail if you are trying to mount a spec with security schemes without assigned handlers
      Note: Router is built when this function is called and the path definition ordering in contract is respected.
      Returns:

    - #### create

          static Future<RouterBuilder> create(Vertx vertx,
                                              String url)

      Create a new `RouterBuilder`
      Parameters:
        `vertx` -
        `url` - location of your spec. It can be an absolute path, a local path or remote url (with HTTP/HTTPS protocol)
      Returns:
        Future completed with success when specification is loaded and valid

    - #### create

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

      Like `this#create(Vertx, String)`

    - #### create

          static Future<RouterBuilder> create(Vertx vertx,
                                              String url,
                                              OpenAPILoaderOptions options)

      Create a new `RouterBuilder`
      Parameters:
        `vertx` -
        `url` - location of your spec. It can be an absolute path, a local path or remote url (with HTTP/HTTPS protocol)
        `options` - options for specification loading
      Returns:
        Future completed with success when specification is loaded and valid

    - #### create

          static void create(Vertx vertx,
                             String url,
                             OpenAPILoaderOptions options,
                             Handler<AsyncResult<RouterBuilder>> handler)

      Like `this#create(Vertx, String, OpenAPILoaderOptions)`

Copyright © 2021 Eclipse. All rights reserved.