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