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

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 $refs

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)