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<auto> h = rc.get("get", "/some_api");

Override Base Path Client Example: # create the RestClient options with a Swagger schema

hash<auto> 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 v2.2.2

fixed handling type declarations with unknown format values (issue 4907)
fixed validating Swagger schemas with objects that declare no properties (issue 4906)

Swagger v2.2.1

fixed a bug converting arguments to fit the Swagger schema to avoid spurious and very difficult to debug type errors (issue 4825)
fixed a bug where any additionalProperties would cause all properties to be accepted (issue 4823)
fixed support of nullable object properties (issue 4854)

Swagger v2.2

implemented lax mode parsing for Swagger schemas with common errors to work (issue 4741)

Swagger v2.1.1

do not require items for arrays not describing a body parameter (issue 4730)
ensure that URI paths are created without duplicated slashes by handling the base path consistently (issue 4728)

Swagger v2.1

parse and report path arguments when processing REST requests on the server side (issue 4661)

Swagger v2.0.10

REST handlers must throw a DESERIALIZATION-ERROR when deserialization errors occur, so that a 400 Bad Request response is returned (issue 4647)
do not reserialize already deserialized data when processing responses (issue 4640)
allow for the client's time zone locale to be set for data serialization / deserialization (issue 4639)

Swagger v2.0.9

fixed a bug where empty definitions could be ignored (issue 4545)

Swagger v2.0.8

do not raise a validation error when a response with an unknown code has a message body; this hides the true error message from the caller in case of error messages (issue 4534)
allow a logger to be set in validators (issue 4509)

Swagger v2.0.7

fixed a bug where global consumes and produces declarations were not respected (issue 4494)

Swagger v2.0.6

fixed a bug where schemas with recursive references could not be loaded (issue 4350)

Swagger v2.0.5

fixed a bug where unknown string format types were not ignored but instead caused an exception to be thrown (issue 4203)

Swagger v2.0.4

fixed a type error in Swagger::getBasePath() for the case when the base path is not set (issue 4064)

Swagger v2.0.3

fixed a bug supporting number formats (issue 3979)

Swagger v2.0.2

fixed date-time value handling (issue 3847)
fixed a bug where sibling elements to a "$ref" were not ignored (see https://swagger.io/docs/specification/using-ref/) (issue 3843)
fixed support for query parameters of type object (issue 3799)

Swagger v2.0.1

added support for the x-nullable attribute to allow for nullable values (issue 3785)
added location support from the FileLocationHandler module (issue 3781)
fixed support for types with no type declaration (issue 3775)

Swagger v2.0

fixed support for additional YAML MIME types (issue 3699)
implemented support for the DataProvider API (issue 3545)

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