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:
[legend]

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

## constructor()

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

## 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 Swagger::SwaggerSchema::getExternalReference | ( | string | refstr | ) |

private

retrieves external references

Exceptions

  INVALID-REFERENCE | invalid reference

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

## processResponseImpl()

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

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

## resolveParameter()

AbstractParameterObject Swagger::SwaggerSchema::resolveParameter | ( | string | name,
|  | string | refstr,
|  | hash | oh
| ) |  |

resolves a reference to a parameter

Exceptions

  INVALID-REFERENCE | invalid reference

## resolveParameterItemsSchemaObject()

ParameterItemsSchemaObject Swagger::SwaggerSchema::resolveParameterItemsSchemaObject | ( | string | name,
|  | string | refstr,
|  | hash | 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 | oh
| ) |  |

resolves a reference to a response

Exceptions

  INVALID-RESPONSE | invalid response

## resolveSchemaObject()

SchemaObject Swagger::SwaggerSchema::resolveSchemaObject | ( | string | name,
|  | string | refstr,
|  | hash | 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.

## private

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 response body can be sent as text/plain and if so, modify the response hash.

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

  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

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

  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

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

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

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