io.vertx.ext.web.api.contract.openapi3.OpenAPI3RouterFactory Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of vertx-web-api-contract Show documentation
There is a newer version: 4.5.11
Show newest version
package io.vertx.ext.web.api.contract.openapi3;

import io.vertx.codegen.annotations.Fluent;
import io.vertx.codegen.annotations.GenIgnore;
import io.vertx.codegen.annotations.VertxGen;
import io.vertx.core.*;
import io.vertx.core.json.JsonObject;
import io.vertx.ext.web.RoutingContext;
import io.vertx.ext.web.api.contract.RouterFactory;
import io.vertx.ext.web.api.contract.openapi3.impl.Utils;
import io.vertx.ext.web.handler.BodyHandler;

import java.util.Collections;
import java.util.List;

/**
 * Interface for OpenAPI3RouterFactory. 

 * To add an handler, use {@link OpenAPI3RouterFactory#addHandlerByOperationId(String, Handler)}

 * Usage example:
 *  * {@code
 * 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:

 *  
 *   Body handler (Customizable with {@link this#setBodyHandler(BodyHandler)}
 *   Custom global handlers configurable with {@link this#addGlobalHandler(Handler)}
 *   Global security handlers defined in upper spec level
 *   Operation specific security handlers
 *   Generated validation handler
 *   User handlers or "Not implemented" handler
 * 
 *
 * @author Francesco Guardiani @slinkydeveloper
 * @deprecated You should use the new module vertx-web-openapi
 */
@VertxGen
@Deprecated
public interface OpenAPI3RouterFactory extends RouterFactory {

  /**
   * Add a particular scope validator. The main security schema will not be called if a specific scope validator is
   * configured
   *
   * @param securitySchemaName
   * @param scopeName
   * @param handler
   * @return this factory
   */
  @Fluent
  OpenAPI3RouterFactory addSecuritySchemaScopeValidator(String securitySchemaName, String scopeName,
                                                        Handler handler);

  /**
   * Add an handler by operation_id field in Operation object
   *
   * @param operationId
   * @param handler
   * @return this factory
   */
  @Fluent
  OpenAPI3RouterFactory addHandlerByOperationId(String operationId, Handler handler);

  /**
   * Add a failure handler by operation_id field in Operation object
   *
   * @param operationId
   * @param failureHandler
   * @return this factory
   */
  @Fluent
  OpenAPI3RouterFactory addFailureHandlerByOperationId(String operationId, Handler failureHandler);

  /**
   * 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
   *
   * @param operationId
   * @param address
   * @return this factory
   */
  @Fluent
  OpenAPI3RouterFactory mountOperationToEventBus(String operationId, 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
   *
   * @param tag
   * @param address
   * @return this factory
   */
  @Fluent
  OpenAPI3RouterFactory mountServiceFromTag(String tag, String address);

  /**
   * 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
   *
   * @return this factory
   */
  @Fluent
  OpenAPI3RouterFactory mountServicesFromExtensions();

  /**
   * 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
   *
   * @return this factory
   */
  @Fluent
  @GenIgnore
  OpenAPI3RouterFactory mountServiceInterface(Class interfaceClass, String address);

  /**
   * Create a new OpenAPI3RouterFactory
   *
   * @param vertx
   * @param url location of your spec. It can be an absolute path, a local path or remote url (with HTTP protocol)
   * @param handler  When specification is loaded, this handler will be called with AsyncResult
   */
  static void create(Vertx vertx, String url, Handler> handler) {
    create(vertx, url, Collections.emptyList(), handler);
  }

  /**
   * @see OpenAPI3RouterFactory#create(Vertx, String, Handler)
   * @param vertx
   * @param url location of your spec. It can be an absolute path, a local path or remote url (with HTTP protocol)
   * @return future When specification is loaded, this future will be called with AsyncResult
   */
  static Future create(Vertx vertx, String url) {
    Promise promise = Promise.promise();
    create(vertx, url, promise);
    return promise.future();
  }

  /**
   * Create a new OpenAPI3RouterFactory
   *
   * @param vertx
   * @param url location of your spec. It can be an absolute path, a local path or remote url (with HTTP protocol)
   * @param auth list of authorization values needed to access the remote url. Each item should be json representation
   *             of an {@code AuthorizationValue}
   * @param handler  When specification is loaded, this handler will be called with AsyncResult
   */
  static void create(Vertx vertx,
                     String url,
                     List auth,
                     Handler> handler) {
    Utils.create(vertx, url, auth, handler);
  }

  /**
   * @see OpenAPI3RouterFactory#create(Vertx, String, Handler)
   * @param vertx
   * @param url location of your spec. It can be an absolute path, a local path or remote url (with HTTP protocol)
   * @param auth list of authorization values needed to access the remote url. Each item should be json representation
   *             of an {@code AuthorizationValue}
   * @return future When specification is loaded, this future will be called with AsyncResult
   */
  static Future create(Vertx vertx, String url, List auth) {
    Promise promise = Promise.promise();
    create(vertx, url, auth, promise);
    return promise.future();
  }
}