Qore Swagger Module Reference
2.0.9
|
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...
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... | |
private hash< RestSchemaValidator::RestExampleRequestInfo > | getExampleRequestImpl (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, AbstractParameterObject > | parameters () |
Parameter definitions that can be used across operations. This property does not define global parameters for all operations. More... | |
private 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... | |
private 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... | |
private 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... | |
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, 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 | |
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::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... | |
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 | |
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.
|
inlineprivate:internal |
Check if the headers contain a content-type header and if so, modify the request hash.
resp | request hash |
body | request body data (if any) |
headers | HTTP headers to include in the request |
Content-Type
header and the rv was modifiedContent-Type
headers, then False is returned and request is not modified
|
inlineprivate:internal |
Check if the headers contain a content-type header and if so, modify the response hash.
resp | response hash |
body | response body data (if any) |
headers | HTTP headers to include in the response |
Content-Type
header and the rv was modifiedContent-Type
headers, then False is returned and response is not modified
|
inlineprivate:internal |
Check if the response body can be sent as text/plain and if so, modify the response hash.
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 |
resp
was modified Builds the schema representation from the deserialized schema hash describing the root document object.
oh | deserialized hash from the source schema description describing the root document object |
opts | options as per SwaggerOptions as follows:
|
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 |
|
private |
Builds the schema representation from the deserialized schema hash describing the root document object.
logger | the logger to use |
oh | deserialized hash from the source schema description describing the root document object |
opts | options as per SwaggerOptions as follows:
|
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 common constructor implementation |
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.
|
private |
returns the base path prefix for all requests in this schema
"/"
is returned
|
private |
returns a data provider object for this connection
rest | the RestClient object to make the connection |
|
inline |
returns a hash of example message information for the given request
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 |
|
inline |
returns a hash of example message information for the given request
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 |
retrieves external references
INVALID-REFERENCE | invalid reference |
|
private |
returns a unique hash for the schema that can be used to compare schemas
returns a hash of URI paths as keys with values as lists of supported HTTP methods
|
private |
returns example Qore code for the given request
method | the HTTP method (case insensitive) |
path | the URI path of the request |
|
private |
returns example Qore code for the given response
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 |
|
private |
returns the target URL for the schema
MISSING-TARGET-URL | no 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.
|
inline |
processes and parses a client request and returns the deserialized message body (if any)
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 |
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 |
|
inline |
parses and validates the response from the server and returns a hash of the processed info
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 |
DESERIALIZATION-ERROR | the response body could not be deserialized or had an invalid Content-Type |
|
inline |
processes a client-side REST request and returns a hash that can be used to make the outgoing client-side HTTP request
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 |
SERIALIZATION-ERROR | unsupported message body MIME type requested or missing serialization module |
|
inlineprivate:internal |
processes a client-side REST request and returns a hash that can be used to make the outgoing client-side HTTP request
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 |
SERIALIZATION-ERROR | unsupported path, message body MIME type requested, or missing serialization module |
|
inline |
processes a REST response with a serialized message body, validates any response data against schema definitions if possible
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 |
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 |
"ACCEPT-ERROR"
must be thrown
|
inlineprivate:internal |
processes a REST response with a serialized message body, validates any response data against schema definitions if possible
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 |
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 |
"ACCEPT-ERROR"
must be thrown AbstractParameterObject Swagger::SwaggerSchema::resolveParameter | ( | string | name, |
string | refstr, | ||
hash< auto > | oh | ||
) |
resolves a reference to a parameter
INVALID-REFERENCE | invalid reference |
ParameterItemsSchemaObject Swagger::SwaggerSchema::resolveParameterItemsSchemaObject | ( | string | name, |
string | refstr, | ||
hash< auto > | oh | ||
) |
resolves a reference to a parameter items schema object
INVALID-REFERENCE | invalid reference |
ResponseObject Swagger::SwaggerSchema::resolveResponse | ( | string | name, |
string | refstr, | ||
hash< auto > | oh | ||
) |
resolves a reference to a response
INVALID-RESPONSE | invalid response |
SchemaObject Swagger::SwaggerSchema::resolveSchemaObject | ( | string | name, |
string | refstr, | ||
hash< auto > | oh | ||
) |
resolves a reference to a schema object
INVALID-REFERENCE | invalid reference |
|
private |
overrides the basePath value
basePath | the new base path value; use an empty string here to clear the 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.
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.
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.
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.
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"
.
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.
|
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)