Qore Swagger Module Reference  0.1
Swagger module

Swagger Module Introduction

The Swagger module provides a Swagger 2.0 REST API validation API to Qore.

The primary classes provided by this module:

  • SwaggerLoader: provides static methods for loading Swagger schemas
  • SwaggerSchema: the Swagger schema object for client/server REST API validation and example code and message generation

This class is most often used in the RestClient and RestHandler modules to register a Swagger 2.0 schema for automatic REST API validation.

JSON and YAML serialization and deserialization are supported; XML is currently not supported.

Swagger Usage

Swagger Client-Side Usage

Use the swagger or validator options in the RestClient::constructor() call to use Swagger 2.0 REST schema validation on the client side with the RestClient class.

To override the target URL specified in the Swagger schema, use the "url" option in the RestClient::constructor() call.

To override the URI base path specified in the Swagger schema, get the Swagger schema object by calling RestClient::getValidator(), and then call AbstractRestSchemaValidator::setBasePath() on the validator object.

Client Example
%new-style
%strict-args
%require-types
%enable-all-warnings
# the RestClient module imports and reexports the Swagger module automatically
%requires RestClient
# create the RestClient options with a Swagger schema
hash opts = (
"swagger": ENV.SCHEMA_DIR + DirSep + "MySchema.yaml",
);
# there is no need to add the "url" option if the target URL provided by the schema is valid
# (otherwise you can override the target URL provided by the Swagger schema by using the
# "url" option in the RestClient constructor options)
RestClient rc(opts);
# afterwards all REST calls made with the RestClient objects with automatic Swagger 2.0
# schema validation; do not include the Swagger schema's basePath in the URI path in the
# requests
hash h = rc.get("get", "/some_api");
Override Base Path Client Example
# create the RestClient options with a Swagger schema
hash opts = (
"swagger": ENV.SCHEMA_DIR + DirSep + "MySchema.yaml",
);
RestClient rc(opts);
# get the SwaggerSchema validator object
AbstractRestSchemaValidator schema = rc.getValidator();
# override the base path in requests
schema.setBasePath("/new/path");

Swagger Server-Side Usage

Enforce Swagger REST API validation on the server side by passing a SwaggerSchema object to the RestHandler::constructor() call as in the following example.

Server Example
%new-style
%strict-args
%require-types
%enable-all-warnings
%requires RestHandler
%requires Swagger
SwaggerSchema swagger = SwaggerLoader::fromFile(ENV.SCHEMA_DIR + DirSep + "MySchema.yaml");
RestHandler handler(NOTHING, swagger);

Swagger Module Release Notes

Swagger v1.0

  • initial release of the Swagger module