Qore Swagger Module Reference  1.0.1
 All Classes Namespaces Functions Variables Groups Pages
Swagger::SwaggerSchema Class Reference

This is the root document object for the API specification. It combines what previously was the Resource Listing and API Declaration (version 1.2 and earlier) together into one document. More...

Inheritance diagram for Swagger::SwaggerSchema:

Public Member Functions

 constructor (hash oh, *hash opts)
 Builds the schema representation from the deserialized schema hash describing the root document object. More...
 
hash< string, SchemaObjectdefinitions ()
 An object to hold data types produced and consumed by operations. More...
 
hash< string,
AbstractParameterObject
parameters ()
 Parameter definitions that can be used across operations. This property does not define global parameters for all operations. More...
 
AbstractParameterObject resolveParameter (string name, string refstr, hash oh)
 resolves a reference to a parameter More...
 
ParameterItemsSchemaObject resolveParameterItemsSchemaObject (string name, string refstr, hash oh)
 resolves a reference to a parameter items schema object More...
 
ResponseObject resolveResponse (string name, string refstr, hash oh)
 resolves a reference to a response More...
 
SchemaObject resolveSchemaObject (string name, string refstr, hash oh)
 resolves a reference to a schema object More...
 
- Public Member Functions inherited from Swagger::ObjectBase
 constructor ()
 Constructor.
 
 constructor (hash oh)
 Constructor. More...
 
 constructor (ObjectBase other)
 copy constructor
 
 initialize (hash oh)
 Initialize. More...
 

Public Attributes

*string basePath
 The base path on which the API is served, which is relative to the host. More...
 
hash< string, bool > consumes
 A set of MIME types (strings) the APIs can consume. More...
 
*ExternalDocumentationObject externalDocs
 Additional external documentation.
 
*string host
 The host (name or IP) serving the API. More...
 
InfoObject info
 Required. Provides metadata about the API. The metadata can be used by the clients if needed.
 
PathsObject paths
 Required. The available paths and operations for the API.
 
 private
 processes a client-side REST request and returns a hash that can be used to make the outgoing client-side HTTP request More...
 
hash< string, bool > produces
 A set of MIME types (strings) the APIs can produce. More...
 
hash< string, ResponseObjectresponses
 Response definitions that can be used across operations. This property does not define global responses for all operations. More...
 
hash< string, bool > schemes
 The transfer protocol of the API. More...
 
hash< string, softlist< string > > security
 A declaration of which security schemes are applied for the API as a whole. More...
 
hash< string,
SecuritySchemeObject
securityDefinitions
 Security scheme definitions that can be used across the specification. More...
 
const SwaggerOptions
 SwaggerSchema options.
 
string swaggerSpec
 Swagger Specification version being used. More...
 
list< TagObjecttags
 A list of tags used by the specification with additional metadata. More...
 
- Public Attributes inherited from Swagger::ObjectBase
hash vendorExtensions
 Allows extensions to the Swagger Schema. More...
 

Private Member Functions

string getBasePathImpl ()
 returns the base path prefix for all requests in this schema More...
 
hash
< RestSchemaValidator::RestExampleRequestInfo
getExampleRequestImpl (string method, string path, *softlist< string > content_types)
 returns a hash of example message information for the given request More...
 
hash< RestExampleResponseInfo > getExampleResponseImpl (string method, string path, int code, *softlist< string > content_types)
 returns a hash of example message information for the given request More...
 
hash getExternalReference (string refstr)
 retrieves external references More...
 
hash< string, list< string > > getPathOperationHashImpl ()
 returns a hash of URI paths as keys with values as lists of supported HTTP methods More...
 
hash< RestQoreExampleCodeInfo > getQoreExampleRequestImpl (string method, string path)
 returns example Qore code for the given request More...
 
hash< RestQoreExampleCodeInfo > getQoreExampleResponseImpl (string method, string path, int code)
 returns example Qore code for the given response More...
 
string getTargetUrlImpl ()
 returns the target URL for the schema More...
 
hash
< RestSchemaValidator::RestRequestServerInfo
parseRequestImpl (string method, string path, *data http_body, reference< hash > headers)
 processes and parses a client request and returns the deserialized message body (if any) More...
 
hash
< RestSchemaValidator::RestResponseClientInfo
parseResponseImpl (string method, string path, int code, *data response_body, hash hdr)
 parses and validates the response from the server and returns a hash of the processed info More...
 
hash
< RestSchemaValidator::RestRequestClientInfo
processRequestImpl (string method, string path, auto body, *hash headers, *softlist< string > content_types)
 processes a client-side REST request and returns a hash that can be used to make the outgoing client-side HTTP request More...
 
hash< HttpResponseInfo > processResponseImpl (string method, string path, int code, auto response_body, *hash headers, *softlist< string > content_types)
 processes a REST response with a serialized message body, validates any response data against schema definitions if possible More...
 
 setBasePathImpl (string basePath)
 overrides the basePath value More...
 

Private Attributes

bool compact_serialization
 if serialized data should be subject to compact serialization (default: True)
 
*string def_path
 the default path to use when retrieving external schema references
 
*code try_import
 a call reference or closure to be passed a string name for external schema references, must take a string argument (the resource name) and return a string (the resource data)
 

Detailed Description

This is the root document object for the API specification. It combines what previously was the Resource Listing and API Declaration (version 1.2 and earlier) together into one document.

Member Function Documentation

Swagger::SwaggerSchema::constructor ( hash  oh,
*hash  opts 
)

Builds the schema representation from the deserialized schema hash describing the root document object.

Parameters
ohdeserialized hash from the source schema description describing the root document object
optsoptions as per SwaggerOptions as follows:
  • compact_serialization (default True): optimize the size of serialized data strings
  • def_path: the default path to use when retrieving external schema references
  • try_import: a call reference or closure to be passed a string name for external schema references, must take a string argument (the resource name) and return a string (the resource data)
Exceptions
SWAGGER-OPTION-ERRORunsuported options in constructor
INVALID-SWAGGER-VERSIONinvalid or missing Swagger schema version
INVALID-FIELD-FORMATfield has an invalid format
INVALID-FIELD-TYPEfield has an invalid type
INVALID-FIELD-VALUEfield has an invalid value
REQUIRED-FIELD-MISSINGrequired field is missing
SECURITY-ERRORinconsistent security information in schema
hash<string, SchemaObject> Swagger::SwaggerSchema::definitions ( )

An object to hold data types produced and consumed by operations.

A hash of SchemaObject objects. Keys are schema names.

string Swagger::SwaggerSchema::getBasePathImpl ( )
private

returns the base path prefix for all requests in this schema

Returns
the base path prefix for all requests in this schema
hash<RestSchemaValidator::RestExampleRequestInfo> Swagger::SwaggerSchema::getExampleRequestImpl ( string  method,
string  path,
*softlist< string content_types 
)
private

returns a hash of example message information for the given request

Parameters
methodthe HTTP method (case insensitive)
paththe URI path of the request
content_typesthe desired MIME types for serialization in order of preference; if none are usable then an exception is thrown
Returns
a RestExampleRequestInfo hash of example message information for the given request
hash<RestExampleResponseInfo> Swagger::SwaggerSchema::getExampleResponseImpl ( string  method,
string  path,
int  code,
*softlist< string content_types 
)
private

returns a hash of example message information for the given request

Parameters
methodthe HTTP method of the original request (case insensitive)
paththe URI path of the original request
codethe HTTP response code of the response
content_typesthe desired MIME types for serialization in order of preference; if none are usable then an exception is thrown
Returns
a RestExampleResponseInfo hash giving example response message info
hash Swagger::SwaggerSchema::getExternalReference ( string  refstr)
private

retrieves external references

Exceptions
INVALID-REFERENCEinvalid reference
hash<string, list<string> > Swagger::SwaggerSchema::getPathOperationHashImpl ( )
private

returns a hash of URI paths as keys with values as lists of supported HTTP methods

Returns
a hash of URI paths as keys with values as lists of supported HTTP methods
hash<RestQoreExampleCodeInfo> Swagger::SwaggerSchema::getQoreExampleRequestImpl ( string  method,
string  path 
)
private

returns example Qore code for the given request

Parameters
methodthe HTTP method (case insensitive)
paththe URI path of the request
Returns
a RestQoreExampleCodeInfo hash giving example Qore code to generate the given request message
hash<RestQoreExampleCodeInfo> Swagger::SwaggerSchema::getQoreExampleResponseImpl ( string  method,
string  path,
int  code 
)
private

returns example Qore code for the given response

Parameters
methodthe HTTP method of the original request (case insensitive)
paththe URI path of the original request
codethe HTTP response code of the response
Returns
a RestQoreExampleCodeInfo hash giving example Qore code to generate the given response message
string Swagger::SwaggerSchema::getTargetUrlImpl ( )
private

returns the target URL for the schema

Returns
the target URL for the schema
Exceptions
MISSING-TARGET-URLno target URL provided for the schema
hash<string, AbstractParameterObject> Swagger::SwaggerSchema::parameters ( )

Parameter definitions that can be used across operations. This property does not define global parameters for all operations.

A hash of AbstractParameterObject objects. Keys are parameter names.

hash<RestSchemaValidator::RestRequestServerInfo> Swagger::SwaggerSchema::parseRequestImpl ( string  method,
string  path,
*data  http_body,
reference< hash headers 
)
private

processes and parses a client request and returns the deserialized message body (if any)

Parameters
methodthe HTTP method (case-insensitive)
paththe URI path with any query arguments
http_bodythe serialized message body
headersa reference to the hash of HTTP headers received; any default header values to be assumed by the server for the request will be added here
Returns
a RestSchemaValidator::RestRequestServerInfo hash of request information
Exceptions
DESERIALIZATION-ERRORthe path does not match the basePath, the request body could not be deserialized or the Content-Type is missing or it is invalid for the operation
hash<RestSchemaValidator::RestResponseClientInfo> Swagger::SwaggerSchema::parseResponseImpl ( string  method,
string  path,
int  code,
*data  response_body,
hash  hdr 
)
private

parses and validates the response from the server and returns a hash of the processed info

Parameters
methodthe HTTP method (case insensitive)
paththe URI path of the original request (without any query arguments)
codethe HTTP response code
response_bodythe HTTP response body data (if any)
hdras hash of HTTP headers received
Returns
a RestSchemaValidator::RestResponseClientInfo hash describing the response
Exceptions
DESERIALIZATION-ERRORthe response body could not be deserialized or had an invalid Content-Type
hash<RestSchemaValidator::RestRequestClientInfo> Swagger::SwaggerSchema::processRequestImpl ( string  method,
string  path,
auto  body,
*hash  headers,
*softlist< string content_types 
)
private

processes a client-side REST request and returns a hash that can be used to make the outgoing client-side HTTP request

Parameters
methodthe HTTP method (case-insensitive)
paththe URI path with any query arguments
bodythe unserialized message body data
headersany headers to include in the request; note that the Content-Type header should not be sent here as it will be overridden when the message is serialized
content_typesthe desired MIME types for serialization in order of preference; if none are usable then an exception is thrown; if this argument is not present, then json is preferred over yaml
Returns
a RestRequestClientInfo hash with information about the request
Exceptions
SERIALIZATION-ERRORunsupported message body MIME type requested or missing serialization module
hash<HttpResponseInfo> Swagger::SwaggerSchema::processResponseImpl ( string  method,
string  path,
int  code,
auto  response_body,
*hash  headers,
*softlist< string content_types 
)
private

processes a REST response with a serialized message body, validates any response data against schema definitions if possible

Parameters
methodthe HTTP method of the original request
paththe URI path of the original request (without query arguments)
codethe HTTP response code
response_bodythe response body data (if any)
headersHTTP headers to include in the response
content_typesthe desired MIME types for serialization in order of preference; if none are usable then an exception is thrown; if this argument is not present, then json is preferred over yaml
Returns
an HttpResponseInfo hash for the response
Exceptions
ACCEPT-ERRORthe response body could not be serialized because the client does not accept a supported type
SERIALIZATION-ERRORthe response body could not be serialized due to an error
Note
<a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html>RFC 2616 section 14</a>: If an Accept header field is present, and if the server cannot send a response which is acceptable according to the combined Accept field value, then the server SHOULD send a 406 (not acceptable) response. To ensure this happens, if an Accept error of this nature occurs in this call, an \c "ACCEPT-ERROR" must be thrown
AbstractParameterObject Swagger::SwaggerSchema::resolveParameter ( string  name,
string  refstr,
hash  oh 
)

resolves a reference to a parameter

Exceptions
INVALID-REFERENCEinvalid reference
ParameterItemsSchemaObject Swagger::SwaggerSchema::resolveParameterItemsSchemaObject ( string  name,
string  refstr,
hash  oh 
)

resolves a reference to a parameter items schema object

Exceptions
INVALID-REFERENCEinvalid reference
ResponseObject Swagger::SwaggerSchema::resolveResponse ( string  name,
string  refstr,
hash  oh 
)

resolves a reference to a response

Exceptions
INVALID-RESPONSEinvalid response
SchemaObject Swagger::SwaggerSchema::resolveSchemaObject ( string  name,
string  refstr,
hash  oh 
)

resolves a reference to a schema object

Exceptions
INVALID-REFERENCEinvalid reference
Swagger::SwaggerSchema::setBasePathImpl ( string  basePath)
private

overrides the basePath value

Parameters
basePaththe new base path value; use an empty string here to clear the basePath

Member Data Documentation

*string Swagger::SwaggerSchema::basePath

The base path on which the API is served, which is relative to the host.

If it is not included, the API is served directly under the host. The value MUST start with a leading slash (/). The basePath does not support path templating.

hash<string, bool> Swagger::SwaggerSchema::consumes

A set of MIME types (strings) the APIs can consume.

This is global to all APIs but can be overridden on specific API calls. Key values MUST be Mime Types.

*string Swagger::SwaggerSchema::host

The host (name or IP) serving the API.

This MUST be the host only and does not include the scheme nor sub-paths. It MAY include a port. If the host is not included, the host serving the documentation is to be used (including the port). The host does not support path templating.

Swagger::SwaggerSchema::private

processes a client-side REST request and returns a hash that can be used to make the outgoing client-side HTTP request

Check if the headers contain a content-type header and if so, modify the response hash.

Check if the headers contain a content-type header and if so, modify the request hash.

processes a REST response with a serialized message body, validates any response data against schema definitions if possible

Parameters
methodthe HTTP method (case-insensitive)
paththe URI path with any query arguments
bodythe unserialized message body data
headersany headers to include in the request; note that the Content-Type header should not be sent here as it will be overridden when the message is serialized
content_typesthe desired MIME types for serialization in order of preference; if none are usable then an exception is thrown; if this argument is not present, then json is preferred over yaml
compact_serializationoverrides the internal compact_serialization flag
Returns
a RestRequestClientInfo hash with information about the request
Exceptions
SERIALIZATION-ERRORunsupported path, message body MIME type requested, or missing serialization module
Parameters
methodthe HTTP method of the original request
paththe URI path of the original request (without query arguments)
codethe HTTP response code
response_bodythe response body data (if any)
headersHTTP headers to include in the response
content_typesthe desired MIME types for serialization in order of preference; if none are usable then an exception is thrown; if this argument is not present, then json is preferred over yaml
compact_serializationallows the compact_serialization property to be overridden
Returns
an HttpResponseInfo hash for the response
Exceptions
ACCEPT-ERRORthe response body could not be serialized because the client does not accept a supported type
SERIALIZATION-ERRORthe response body could not be serialized due to an error
Note
<a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html>RFC 2616 section 14</a>: If an Accept header field is present, and if the server cannot send a response which is acceptable according to the combined Accept field value, then the server SHOULD send a 406 (not acceptable) response. To ensure this happens, if an Accept error of this nature occurs in this call, an \c "ACCEPT-ERROR" must be thrown
Parameters
resprequest hash
bodyrequest body data (if any)
headersHTTP headers to include in the request
Returns
whether the headers contained a Content-Type header and the rv was modified
Note
if there are more Content-Type headers, then False is returned and request is not modified
Parameters
respresponse hash
bodyresponse body data (if any)
headersHTTP headers to include in the response
Returns
whether the headers contained a Content-Type header and the rv was modified
Note
if there are more Content-Type headers, then False is returned and response is not modified
hash<string, bool> Swagger::SwaggerSchema::produces

A set of MIME types (strings) the APIs can produce.

This is global to all APIs but can be overridden on specific API calls. Key values MUST be Mime Types.

hash<string, ResponseObject> Swagger::SwaggerSchema::responses

Response definitions that can be used across operations. This property does not define global responses for all operations.

A hash of ResponseObject objects. Keys are response names.

hash<string, bool> Swagger::SwaggerSchema::schemes

The transfer protocol of the API.

Values MUST be from the list: "http", "https", "ws", "wss". If the schemes is not included, the default scheme to be used is the one used to access the Swagger definition itself.

hash<string, softlist<string> > Swagger::SwaggerSchema::security

A declaration of which security schemes are applied for the API as a whole.

The list of values describes alternative security schemes that can be used (that is, there is a logical OR between the security requirements). Individual operations can override this definition.

Individual values are hashes in the form of Security Requirement Objects. See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#securityRequirementObject. That is, the hash keys MUST correspond to security schemes declared in the Security Definitions, while the values are lists of scope names (strings) required for the execution.

hash<string, SecuritySchemeObject> Swagger::SwaggerSchema::securityDefinitions

Security scheme definitions that can be used across the specification.

A hash of SecuritySchemeObject objects. Keys are scheme names.

string Swagger::SwaggerSchema::swaggerSpec

Swagger Specification version being used.

It can be used by the Swagger UI and other clients to interpret the API listing. The value MUST be "2.0".

list<TagObject> Swagger::SwaggerSchema::tags

A list of tags used by the specification with additional metadata.

The order of the tags can be used to reflect on their order by the parsing tools. Not all tags that are used by the OperationObject must be declared. The tags that are not declared may be organized randomly or based on the tools' logic. Each tag name in the list MUST be unique.

Individual values in this list are of type TagObject.