| Qore Swagger Module Reference 2.2.3

Loading...
Searching...
No Matches
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<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.3

- improved parsing Swagger schemas with type errors

## 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)
- implemented the `utc_dates` and `query_date_format` options

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