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
default RouterBuilder	bodyHandler(BodyHandler bodyHandler) Deprecated. Use rootHandler(Handler) instead. The order matters, so adding the body handler should happen after any PLATFORM or SECURITY_POLICY handler(s).
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() Deprecated. This method exposes the internal of the OpenAPI handler, it will be removed in the future. Users should configure the json schema module from the options.
SchemaRouter	getSchemaRouter() Deprecated. This method exposes the internal of the OpenAPI handler, it will be removed in the future. Users should configure the json schema module from the options.
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.
SecurityScheme	securityHandler(String securitySchemeName) Creates a new security scheme for the required AuthenticationHandler.
RouterBuilder	securityHandler(String securitySchemeName, 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

@Deprecated
default RouterBuilder bodyHandler(BodyHandler bodyHandler)

Deprecated. Use rootHandler(Handler) instead. The order matters, so adding the body handler should happen after any PLATFORM or SECURITY_POLICY handler(s).

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 securitySchemeName,
                              AuthenticationHandler handler)

Mount to paths that have to follow a security schema a security handler. This method will not perform any validation weather or not the given securitySchemeName is present in the OpenAPI document. For must use cases the method securityHandler(String) should be used.

Parameters:

securitySchemeName - the components security scheme id

handler - the authentication 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

@Deprecated
SchemaRouter getSchemaRouter()

Deprecated. This method exposes the internal of the OpenAPI handler, it will be removed in the future. Users should configure the json schema module from the options.

Returns:

schema router used by self to internally manage all Schema instances

getSchemaParser

@Deprecated
SchemaParser getSchemaParser()

Deprecated. This method exposes the internal of the OpenAPI handler, it will be removed in the future. Users should configure the json schema module from the options.

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

securityHandler

SecurityScheme securityHandler(String securitySchemeName)

Creates a new security scheme for the required AuthenticationHandler.

Returns:

a security scheme.

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)