Skip to main content

Vert.x-Web API合同为Vert.x带来了两个功能,可帮助您开发API:

  • HTTP请求验证

  • 具有自动请求验证的OpenAPI 3支持

Using Vert.x API Contract

要使用Vert.x API Contract,请将以下依赖项添加到构建描述符的" dependencies"部分:

  • Maven(在您的pom.xml ):

<dependency>
  <groupId>io.vertx</groupId>
  <artifactId>vertx-web-api-contract</artifactId>
  <version>3.5.4</version>
</dependency>
  • Gradle(在您的build.gradle文件中):

dependencies {
  compile 'io.vertx:vertx-web-api-contract:3.5.4'
}

HTTP Requests validation

Vert.x提供了一个验证框架,该框架将为您验证请求并将验证结果放入容器中.

定义一个HTTPRequestValidationHandler

require 'vertx-web-api-contract/http_request_validation_handler'
# Create Validation Handler with some stuff
validationHandler = VertxWebApiContract::HTTPRequestValidationHandler.create().add_query_param("parameterName", :INT, true).add_form_param_with_pattern("formParameterName", "a{4}", true).add_path_param("pathParam", :FLOAT)

然后,您可以安装验证处理程序:

require 'vertx-web/body_handler'
# BodyHandler is required to manage body parameters like forms or json body
router.route().handler(&VertxWeb::BodyHandler.create().method(:handle))

router.get("/awesome/:pathParam").handler(&validationHandler.method(:handle)).handler() { |routingContext|
  # Get Request parameters container
  params = routingContext.get("parsedParameters")

  # Get parameters
  parameterName = params.query_parameter("parameterName").get_integer()
  formParameterName = params.form_parameter("formParameterName").get_string()
  pathParam = params.path_parameter("pathParam").get_float()
}.failure_handler() { |routingContext|
  failure = routingContext.failure()
  if (failure.class.name == 'Java::IoVertxExtWebApiValidation::ValidationException')
    # Something went wrong during validation!
    validationErrorMessage = failure.get_message()
  end
}

如果验证成功,则在RequestParameters内返回请求参数,否则将抛出ValidationException

Types of request parameters

每个参数都有一个类型验证器,一个描述所需参数类型的类. 类型验证器验证该值,将其转换为所需的语言类型,然后将其加载到RequestParameter对象中. 有三种方法来描述参数的类型:

Handling parameters

现在您可以处理参数值:

params = routingContext.get("parsedParameters")
awesomeParameter = params.query_parameter("awesomeParameter")
if (awesomeParameter != nil)
  if (!awesomeParameter.empty?())
    # Parameter exists and isn't empty
    # ParameterTypeValidator mapped the parameter in equivalent language object
    awesome = awesomeParameter.get_integer()
  else
    # Parameter exists, but it's empty
  end
else
  # Parameter doesn't exist (it's not required)
end

如您所见,每个参数都映射到相应的语言对象中. 您还可以获取json正文:

body = params.body()
if (body != nil)
  jsonBody = body.get_json_object()
end

OpenAPI 3 support

Vert.x允许您使用设计优先的方法在代码内直接使用OpenApi 3规范. Vert.x-Web提供:

  • 通过自动加载外部Json模式来验证符合OpenAPI 3的API规范

  • 自动请求验证

  • 自动安装安全验证处理程序

  • 未执行的操作会自动进行501响应

  • 路由器工厂向用户提供所有这些功能

您还可以使用社区项目slush-vertx从OpenAPI 3规范中生成服务器代码.

The router factory

您可以使用OpenAPI3RouterFactory基于OpenAPI3规范创建Web服务. 顾名思义,此类是基于您的OpenAPI 3规范的路由器工厂. OpenAPI3RouterFactory旨在为您提供一个非常简单的用户界面,以使用OpenAPI 3支持. 这包括:

  • 规范的异步加载及其架构依赖性

  • 使用operationId或结合路径和HTTP方法安装路径

  • 自动请求参数验证

  • 自动将OpenAPI样式路径转换为Vert.x样式路径

  • 惰性方法:操作(路径和HTTP方法的组合)按规范内的声明顺序装入

  • 自动安装安全验证处理程序

Create a new router factory

To create a new router factory, Use method OpenAPI3RouterFactory.create. As location It accepts absolute paths, local paths and local or remote URLs (HTTP or file protocol).

例如:

require 'vertx-web-api-contract/open_api3_router_factory'
VertxWebApiContract::OpenAPI3RouterFactory.create(vertx, "src/main/resources/petstore.yaml") { |ar_err,ar|
  if (ar_err == nil)
    # Spec loaded with success
    routerFactory = ar
  else
    # Something went wrong during router factory initialization
    exception = ar_err
  end
}

您还可以根据远程规范构建路由器工厂:

require 'vertx-web-api-contract/open_api3_router_factory'
VertxWebApiContract::OpenAPI3RouterFactory.create(vertx, "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore.yaml") { |ar_err,ar|
  if (ar_err == nil)
    # Spec loaded with success
    routerFactory = ar
  else
    # Something went wrong during router factory initialization
    exception = ar_err
  end
}

您还可以使用RouterFactoryOptions修改路由器工厂的行为. 例如,您可以要求路由器工厂挂载验证失败处理程序,但不挂载未实现的处理程序,如下所示:

routerFactory = ar.result()
# Create and mount options to router factory
options = {
  'mountNotImplementedHandler' => true,
  'mountValidationFailureHandler' => false
}

routerFactory.set_options(options)

Mount the handlers

现在加载您的第一个路径. 有两个函数可以加载处理程序:

当然,还有两个函数可以加载故障处理程序

当然,您可以将多个处理程序添加到同一操作中 ,而不会覆盖现有的处理程序 .

Important
OpenAPI格式的路径
如果你想使用addHandleraddFailureHandler注意:您只能在OpenAPI的风格提供了一个路径(例如路径/hello/:param不工作)

例如:

routerFactory.add_handler_by_operation_id("awesomeOperation") { |routingContext|
  params = routingContext.get("parsedParameters")
  body = params.body()
  jsonBody = body.get_json_object()
  # Do something with body
}
routerFactory.add_failure_handler_by_operation_id("awesomeOperation") { |routingContext|
  # Handle failure
}
Important
使用operationId添加操作
允许结合使用路径和HTTP方法,但是出于性能原因并避免路径命名错误,最好使用operationId添加操作处理程序

现在您可以如上所述使用参数值

Define security handlers

安全处理程序由架构名称和范围的组合定义. 您只能为组合安装一个安全处理程序. 例如:

routerFactory.add_security_handler("security_scheme_name", &securityHandler)

您当然可以使用随附的Vert.x安全处理程序,例如:

require 'vertx-web/jwt_auth_handler'
routerFactory.add_security_handler("jwt_auth", &VertxWeb::JWTAuthHandler.create(jwtAuthProvider).method(:handle))

Customize the router factory behaviours

路由器工厂允许您使用RouterFactoryOptions自定义路由器生成过程中的某些行为. 路由器工厂可以:

  • 为尚未安装任何处理程序的操作安装501 Not Implemented处理程序

  • 挂载一个管理ValidationException的400 Bad Request处理程序

  • 必要时挂载ResponseContentTypeHandler处理程序

深入了解RouterFactoryOptions文档

Generate the router

准备就绪后,生成路由器并使用它:

router = routerFactory.get_router()

server = vertx.create_http_server({
  'port' => 8080,
  'host' => "localhost"
})
server.request_handler(&router.method(:accept)).listen()

by  ICOPY.SITE