Qore Swagger Module Reference  2.0.9
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 Methods

 constructor (string schema_source, hash< auto > oh, *hash< auto > 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...
 
private hash< RestSchemaValidator::RestExampleRequestInfogetExampleRequestImpl (string method, string path, *softlist< string > content_types)
 returns a hash of example message information for the given request More...
 
private 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< string, AbstractParameterObjectparameters ()
 Parameter definitions that can be used across operations. This property does not define global parameters for all operations. More...
 
private hash< RestSchemaValidator::RestRequestServerInfoparseRequestImpl (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...
 
private hash< RestSchemaValidator::RestResponseClientInfoparseResponseImpl (string method, string path, int code, *data response_body, hash< auto > hdr)
 parses and validates the response from the server and returns a hash of the processed info More...
 
private hash< RestSchemaValidator::RestRequestClientInfoprocessRequestImpl (string method, string path, auto body, *hash< auto > 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...
 
private hash< HttpResponseInfo > processResponseImpl (string method, string path, int code, auto response_body, *hash< auto > headers, *softlist< string > content_types)
 processes a REST response with a serialized message body, validates any response data against schema definitions if possible More...
 
AbstractParameterObject resolveParameter (string name, string refstr, hash< auto > oh)
 resolves a reference to a parameter More...
 
ParameterItemsSchemaObject resolveParameterItemsSchemaObject (string name, string refstr, hash< auto > oh)
 resolves a reference to a parameter items schema object More...
 
ResponseObject resolveResponse (string name, string refstr, hash< auto > oh)
 resolves a reference to a response More...
 
SchemaObject resolveSchemaObject (string name, string refstr, hash< auto > oh)
 resolves a reference to a schema object More...
 
- Public Member Methods inherited from Swagger::ObjectBase
 constructor ()
 Constructor.
 
 constructor (hash< auto > oh)
 Constructor. More...
 
 constructor (ObjectBase other)
 copy constructor
 
 initialize (hash< auto > 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.
 
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, SecuritySchemeObjectsecurityDefinitions
 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< auto > vendorExtensions
 Allows extensions to the Swagger Schema. More...
 

Private Member Methods

 constructorIntern (string schema_source, hash< auto > oh, *hash< auto > opts)
 Builds the schema representation from the deserialized schema hash describing the root document object. More...
 
 fixPath (reference< string > path)
 removes the base path from the beginning of the path, if present
 
string getBasePathImpl ()
 returns the base path prefix for all requests in this schema More...
 
AbstractDataProvider getDataProviderImpl (HTTPClient rest)
 returns a data provider object for this connection More...
 
hash< auto > getExternalReference (string refstr)
 retrieves external references More...
 
string getHashImpl ()
 returns a unique hash for the schema that can be used to compare schemas 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...
 
 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
 
string hash_str
 the hash for the schema
 
hash< string, hash< string, SchemaObject > > so_map
 maps name -> SHA1 hash of the config -> schema objects for recursive references
 
*code try_import
 a call reference or closure to be passed a string name for external schema references More...
 

Private:Internal Member Methods

internal bool checkRequestContentTypeHeader (reference< hash< RestRequestClientInfo >> req, auto body, *hash< auto > headers)
 Check if the headers contain a content-type header and if so, modify the request hash. More...
 
internal bool checkResponseContentTypeHeader (reference< hash< HttpResponseInfo >> resp, auto body, *hash< auto > headers)
 Check if the headers contain a content-type header and if so, modify the response hash. More...
 
internal bool checkResponseTextPlain (reference< hash< HttpResponseInfo >> resp, auto body, hash< string, bool > mime_types, *list< auto > content_types)
 Check if the response body can be sent as text/plain and if so, modify the response hash. More...
 
SchemaObject processDefinition (string key, auto value)
 Processes a schema definition.
 
internal hash< RestSchemaValidator::RestRequestClientInfoprocessRequestIntern (string method, string path, auto body, *hash< auto > headers, *softlist< string > content_types, bool compact_serialization)
 processes a client-side REST request and returns a hash that can be used to make the outgoing client-side HTTP request More...
 
internal hash< HttpResponseInfo > processResponseIntern (string method, string path, int code, auto response_body, *hash< auto > headers, *softlist< string > content_types, bool compact_serialization)
 processes a REST response with a serialized message body, validates any response data against schema definitions if possible More...
 

Private:Internal Attributes

*hash< auto > source_definition_hash
 the raw parsed definitions; used for resolving out-of-order references
 

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

◆ checkRequestContentTypeHeader()

internal bool Swagger::SwaggerSchema::checkRequestContentTypeHeader ( reference< hash< RestRequestClientInfo >>  req,
auto  body,
*hash< auto >  headers 
)
inlineprivate:internal

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

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

◆ checkResponseContentTypeHeader()

internal bool Swagger::SwaggerSchema::checkResponseContentTypeHeader ( reference< hash< HttpResponseInfo >>  resp,
auto  body,
*hash< auto >  headers 
)
inlineprivate:internal

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

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

◆ checkResponseTextPlain()

internal bool Swagger::SwaggerSchema::checkResponseTextPlain ( reference< hash< HttpResponseInfo >>  resp,
auto  body,
hash< string, bool >  mime_types,
*list< auto >  content_types 
)
inlineprivate:internal

Check if the response body can be sent as text/plain and if so, modify the response hash.

Parameters
respresponse hash
bodyresponse body data (if any)
mime_typesMIME types produced by the operation
content_typescontent types accepted by the client
Returns
whether the response body can be sent as text/plain and the resp was modified

◆ constructor()

Swagger::SwaggerSchema::constructor ( string  schema_source,
hash< auto >  oh,
*hash< auto >  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

◆ constructorIntern()

Swagger::SwaggerSchema::constructorIntern ( string  schema_source,
hash< auto >  oh,
*hash< auto >  opts 
)
private

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

Parameters
loggerthe logger to use
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 common constructor implementation

◆ definitions()

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.

◆ getBasePathImpl()

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
Note
if none is set, then "/" is returned

◆ getDataProviderImpl()

AbstractDataProvider Swagger::SwaggerSchema::getDataProviderImpl ( HTTPClient  rest)
private

returns a data provider object for this connection

Parameters
restthe RestClient object to make the connection
Returns
a data provider object for this connection, if supported by any REST schema validator object

◆ getExampleRequestImpl()

private hash<RestSchemaValidator::RestExampleRequestInfo> Swagger::SwaggerSchema::getExampleRequestImpl ( string  method,
string  path,
*softlist< string content_types 
)
inline

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

◆ getExampleResponseImpl()

private hash<RestExampleResponseInfo> Swagger::SwaggerSchema::getExampleResponseImpl ( string  method,
string  path,
int  code,
*softlist< string content_types 
)
inline

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

◆ getExternalReference()

hash<auto> Swagger::SwaggerSchema::getExternalReference ( string  refstr)
private

retrieves external references

Exceptions
INVALID-REFERENCEinvalid reference

◆ getHashImpl()

string Swagger::SwaggerSchema::getHashImpl ( )
private

returns a unique hash for the schema that can be used to compare schemas

Returns
a unique hash for the schema that can be used to compare schemas
Since
Swagger 2.0

◆ getPathOperationHashImpl()

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

◆ getQoreExampleRequestImpl()

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

◆ getQoreExampleResponseImpl()

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

◆ getTargetUrlImpl()

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

◆ parameters()

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.

◆ parseRequestImpl()

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

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

◆ parseResponseImpl()

private hash<RestSchemaValidator::RestResponseClientInfo> Swagger::SwaggerSchema::parseResponseImpl ( string  method,
string  path,
int  code,
*data  response_body,
hash< auto >  hdr 
)
inline

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

◆ processRequestImpl()

private hash<RestSchemaValidator::RestRequestClientInfo> Swagger::SwaggerSchema::processRequestImpl ( string  method,
string  path,
auto  body,
*hash< auto >  headers,
*softlist< string content_types 
)
inline

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

◆ processRequestIntern()

internal hash<RestSchemaValidator::RestRequestClientInfo> Swagger::SwaggerSchema::processRequestIntern ( string  method,
string  path,
auto  body,
*hash< auto >  headers,
*softlist< string content_types,
bool  compact_serialization 
)
inlineprivate:internal

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

◆ processResponseImpl()

private hash<HttpResponseInfo> Swagger::SwaggerSchema::processResponseImpl ( string  method,
string  path,
int  code,
auto  response_body,
*hash< auto >  headers,
*softlist< string content_types 
)
inline

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: 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 "ACCEPT-ERROR" must be thrown

◆ processResponseIntern()

internal hash<HttpResponseInfo> Swagger::SwaggerSchema::processResponseIntern ( string  method,
string  path,
int  code,
auto  response_body,
*hash< auto >  headers,
*softlist< string content_types,
bool  compact_serialization 
)
inlineprivate:internal

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
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: 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 "ACCEPT-ERROR" must be thrown

◆ resolveParameter()

AbstractParameterObject Swagger::SwaggerSchema::resolveParameter ( string  name,
string  refstr,
hash< auto >  oh 
)

resolves a reference to a parameter

Exceptions
INVALID-REFERENCEinvalid reference

◆ resolveParameterItemsSchemaObject()

ParameterItemsSchemaObject Swagger::SwaggerSchema::resolveParameterItemsSchemaObject ( string  name,
string  refstr,
hash< auto >  oh 
)

resolves a reference to a parameter items schema object

Exceptions
INVALID-REFERENCEinvalid reference

◆ resolveResponse()

ResponseObject Swagger::SwaggerSchema::resolveResponse ( string  name,
string  refstr,
hash< auto >  oh 
)

resolves a reference to a response

Exceptions
INVALID-RESPONSEinvalid response

◆ resolveSchemaObject()

SchemaObject Swagger::SwaggerSchema::resolveSchemaObject ( string  name,
string  refstr,
hash< auto >  oh 
)

resolves a reference to a schema object

Exceptions
INVALID-REFERENCEinvalid reference

◆ setBasePathImpl()

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

◆ basePath

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

◆ consumes

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.

◆ host

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

◆ produces

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.

◆ responses

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.

◆ schemes

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.

◆ security

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.

◆ securityDefinitions

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.

◆ swaggerSpec

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

◆ tags

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.

◆ try_import

*code Swagger::SwaggerSchema::try_import
private

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)