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.1.0

fixed accepting multipart/form-data content-type and also working with list and hash parameters (issue 2932)

Swagger v1.0.2

fixed sending of simple string responses to use text/plain Content-Type if possible (issue 2893)
fixed checking of response body in case response schema is not present (issue 2894)

Swagger v1.0.1

fixed handling of string type date and date-time formats (issue 2341)
fixed example value for binary type (issue 2342)
fixed serialization of date/time values (issue 2349)
fixed handling of non-string enum types (issue 2364)
fixed confusing error messages with invalid parameter types (issue 2365)
fixed handling of messages with non-object (i.e. non-hash) bodies (issue 2366)
fixed handling of optional parameters (issue 2369)
fixed handling of non-string query parameters (issue 2388)
fixed a bug where string value constraints were only enforced in requests but not responses (issue 2396)
fixed a bug where invalid date, binary, and byte values would cause a 500 Internal Server Error response to be returned instead of a 400 Bad Request error (issue 2397)
fixed a bug where date values were formatted incorrectly in Swagger responses (issue 2409)
fixed a bug which made it impossible to send data with other content/mime types than json, yamlrpc, FormUrlEncoded or MultipartFormData (issue 2497)
fixed handling of string/binary values (issue 2505)
fixed a bug where consumes property of operations was sometimes ignored (issue 2507)
fixed parsing of responses without Content-Type header (issue 2517)
fixed path matching for paths not beginning with a slash (issue 2516)

Swagger v1.0

initial release of the Swagger module

Table of Contents