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
%requires RestClient
hash opts = (
"swagger": ENV.SCHEMA_DIR + DirSep + "MySchema.yaml",
);
RestClient rc(opts);
hash<auto> h = rc.get("get", "/some_api");
- Override Base Path Client Example
hash<auto> opts = (
"swagger": ENV.SCHEMA_DIR + DirSep + "MySchema.yaml",
);
RestClient rc(opts);
AbstractRestSchemaValidator schema = rc.getValidator();
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.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
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