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:

[legend]

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, SchemaObject >	definitions ()
	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< 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, ResponseObject >	responses
	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< TagObject >	tags
	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
	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< 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< 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...

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

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

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

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

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.

hash< RestSchemaValidator::RestRequestClientInfo >	processRequestIntern (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...

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

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

private:internal

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

Parameters

resp	request hash
body	request body data (if any)
headers	HTTP 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()

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

private:internal

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

Parameters

resp	response hash
body	response body data (if any)
headers	HTTP 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()

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

private:internal

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

Parameters

resp	response hash
body	response body data (if any)
mime_types	MIME types produced by the operation
content_types	content 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

oh	deserialized hash from the source schema description describing the root document object
opts	options 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-ERROR	unsuported options in constructor
INVALID-SWAGGER-VERSION	invalid or missing Swagger schema version
INVALID-FIELD-FORMAT	field has an invalid format
INVALID-FIELD-TYPE	field has an invalid type
INVALID-FIELD-VALUE	field has an invalid value
REQUIRED-FIELD-MISSING	required field is missing
SECURITY-ERROR	inconsistent security information in schema

◆ 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

rest	the `RestClient` object to make the connection

Returns: a data provider object for this connection, if supported by any REST schema validator object

◆ getExampleRequestImpl()

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

method	the HTTP method (case insensitive)
path	the URI path of the request
content_types	the 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()

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

method	the HTTP method of the original request (case insensitive)
path	the URI path of the original request
code	the HTTP response code of the response
content_types	the 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-REFERENCE invalid 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

method	the HTTP method (case insensitive)
path	the 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

method	the HTTP method of the original request (case insensitive)
path	the URI path of the original request
code	the 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-URL no 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()

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

method	the HTTP method (case-insensitive)
path	the URI path with any query arguments
http_body	the serialized message body
headers	a 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-ERROR the 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()

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

private

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

Parameters

method	the HTTP method (case insensitive)
path	the URI path of the original request (without any query arguments)
code	the HTTP response code
response_body	the HTTP response body data (if any)
hdr	as hash of HTTP headers received

Returns: a RestSchemaValidator::RestResponseClientInfo hash describing the response

Exceptions

DESERIALIZATION-ERROR the response body could not be deserialized or had an invalid Content-Type

◆ processRequestImpl()

hash<RestSchemaValidator::RestRequestClientInfo> Swagger::SwaggerSchema::processRequestImpl	(	string	method,
		string	path,
		auto	body,
		*hash< auto >	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

method	the HTTP method (case-insensitive)
path	the URI path with any query arguments
body	the unserialized message body data
headers	any 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_types	the 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-ERROR unsupported message body MIME type requested or missing serialization module

◆ processRequestIntern()

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

private:internal

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

Parameters

method	the HTTP method (case-insensitive)
path	the URI path with any query arguments
body	the unserialized message body data
headers	any 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_types	the 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_serialization	overrides the internal `compact_serialization` flag

Returns: a RestRequestClientInfo hash with information about the request

Exceptions

SERIALIZATION-ERROR unsupported path, message body MIME type requested, or missing serialization module

◆ processResponseImpl()

hash<HttpResponseInfo> Swagger::SwaggerSchema::processResponseImpl	(	string	method,
		string	path,
		int	code,
		auto	response_body,
		*hash< auto >	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

method	the HTTP method of the original request
path	the URI path of the original request (without query arguments)
code	the HTTP response code
response_body	the response body data (if any)
headers	HTTP headers to include in the response
content_types	the 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-ERROR	the response body could not be serialized because the client does not accept a supported type
SERIALIZATION-ERROR	the 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()

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

private:internal

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

Parameters

method	the HTTP method of the original request
path	the URI path of the original request (without query arguments)
code	the HTTP response code
response_body	the response body data (if any)
headers	HTTP headers to include in the response
content_types	the 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_serialization	allows the compact_serialization property to be overridden

Returns: an HttpResponseInfo hash for the response

Exceptions

ACCEPT-ERROR	the response body could not be serialized because the client does not accept a supported type
SERIALIZATION-ERROR	the 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-REFERENCE invalid reference

◆ resolveParameterItemsSchemaObject()

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

resolves a reference to a parameter items schema object

Exceptions

INVALID-REFERENCE invalid reference

◆ resolveResponse()

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

resolves a reference to a response

Exceptions

INVALID-RESPONSE invalid response

◆ resolveSchemaObject()

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

resolves a reference to a schema object

Exceptions

INVALID-REFERENCE invalid reference

◆ setBasePathImpl()

Swagger::SwaggerSchema::setBasePathImpl ( string basePath )

private

overrides the basePath value

Parameters

basePath the 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)

Public Member Methods

Public Attributes

Private Member Methods

Private Attributes

Private:Internal Member Methods

Private:Internal Attributes

Detailed Description

Member Function Documentation

◆ checkRequestContentTypeHeader()

◆ checkResponseContentTypeHeader()

◆ checkResponseTextPlain()

◆ constructor()

◆ definitions()

◆ getBasePathImpl()

◆ getDataProviderImpl()

◆ getExampleRequestImpl()

◆ getExampleResponseImpl()

◆ getExternalReference()

◆ getHashImpl()

◆ getPathOperationHashImpl()

◆ getQoreExampleRequestImpl()

◆ getQoreExampleResponseImpl()

◆ getTargetUrlImpl()

◆ parameters()

◆ parseRequestImpl()

◆ parseResponseImpl()

◆ processRequestImpl()

◆ processRequestIntern()

◆ processResponseImpl()

◆ processResponseIntern()

◆ resolveParameter()

◆ resolveParameterItemsSchemaObject()

◆ resolveResponse()

◆ resolveSchemaObject()

◆ setBasePathImpl()

Member Data Documentation

◆ basePath

◆ consumes

◆ host

◆ produces

◆ responses

◆ schemes

◆ security

◆ securityDefinitions

◆ swaggerSpec

◆ tags

◆ try_import