Qore Swagger Module Reference  1.1.0
Swagger::OperationObject Class Reference

Describes a single API operation on a path. More...

Inheritance diagram for Swagger::OperationObject:

Public Member Methods

 constructor (string path, string method, hash oh, SwaggerSchema swagger)
 Constructor. More...
 
hash< RestSchemaValidator::RestExampleRequestInfogetExampleRequest (string method, string path, PathItemObject pio, SwaggerSchema swagger, reference rbody)
 returns a hash of example message information for the given request More...
 
hash< RestExampleResponseInfo > getExampleResponse (string method, string path, int code, reference body)
 returns a hash of example message information for the given request More...
 
hash< RestQoreExampleCodeInfo > getQoreExampleRequest (string method, string path, PathItemObject pio, SwaggerSchema swagger)
 returns example Qore code for the given request More...
 
hash< RestQoreExampleCodeInfo > getQoreExampleResponse (string method, string path, int code)
 returns example Qore code for the given response More...
 
hash< string, AbstractParameterObjectparameters ()
 A hash of parameters that are applicable for this operation. More...
 
 parseRequest (PathItemObject pio, reference< hash< UriQueryInfo >> h, reference< auto > body, reference< hash > headers)
 parses and processes a REST request on the server side More...
 
 validateRequest (bool serialize, PathItemObject pio, reference< hash< UriQueryInfo >> h, reference< auto > body, reference< hash > headers, *reference< hash< string, bool >> mime_types)
 processes a REST API client-side request to the operation More...
 
 validateResponse (string method, string path, PathItemObject pio, int code, reference< auto > response_body, reference< hash< string, bool >> mime_types)
 validates a response against the response definition, if any
 
- Public Member Methods inherited from Swagger::ObjectBase
 constructor ()
 Constructor.
 
 constructor (hash oh)
 Constructor. More...
 
 constructor (ObjectBase other)
 copy constructor
 
 initialize (hash oh)
 Initialize. More...
 

Public Attributes

AbstractParameterObject body
 body parameter; if defined for this operation, formData parameter will be excluded
 
hash< string, bool > consumes
 A list of MIME types (strings) the operation can consume. More...
 
bool deprec = False
 Declares this operation to be deprecated. More...
 
*string desc
 A verbose explanation of the operation behavior. GFM syntax can be used for rich text representation.
 
*ExternalDocumentationObject externalDocs
 Additional external documentation for this operation.
 
AbstractParameterObject formData
 formData parameter; if defined for this operation, body parameter will be excluded
 
string method
 the HTTP method for the operation
 
*string operationId
 Unique string used to identify the operation. More...
 
string path
 the URI path for the operation
 
hash< string, bool > produces
 A hash of MIME types (strings) the operation can produce. More...
 
ResponsesObject responses
 Required. The list of possible responses as they are returned from executing this operation.
 
list< stringschemes
 The transfer protocol for the operation. More...
 
list< hash< string, list< string > > > security
 A declaration of which security schemes are applied for this operation. More...
 
*string summary
 A short summary of what the operation does.
 
list tags
 A list of tags (strings or TagObjects) for API documentation control. More...
 
- Public Attributes inherited from Swagger::ObjectBase
hash vendorExtensions
 Allows extensions to the Swagger Schema. More...
 

Private Member Methods

 checkMissingParams (hash< UriQueryInfo > h, *hash headers, auto body, hash< string, AbstractParameterObject > parameters, *hash< string, AbstractParameterObject > child_params)
 checks for missing params
 
 doDefaultParams (reference< hash< UriQueryInfo >> h, reference< hash > headers, reference< auto > body, hash< string, AbstractParameterObject > parameters, *hash< string, AbstractParameterObject > child_params)
 add default parameters
 
 error (string err, string fmt)
 raises an exception with context information
 
*ResponseObject getResponse (int code)
 returns the ResponseObject for hthe given HTTP code or NOTHING if none is configured More...
 

Detailed Description

Describes a single API operation on a path.

Member Function Documentation

◆ constructor()

Swagger::OperationObject::constructor ( string  path,
string  method,
hash  oh,
SwaggerSchema  swagger 
)

Constructor.

Parameters
paththe path for the operation
methodthe HTTP method for the operation
ohdeserialized hash from the source schema description describing the operation
swaggerthe REST schema for resolving references
Exceptions
INVALID-FIELD-TYPEfield has invalid type
INVALID-FIELD-VALUEfield has invalid value
REQUIRED-FIELD-MISSINGrequired field is missing

◆ getExampleRequest()

hash<RestSchemaValidator::RestExampleRequestInfo> Swagger::OperationObject::getExampleRequest ( string  method,
string  path,
PathItemObject  pio,
SwaggerSchema  swagger,
reference  rbody 
)

returns a hash of example message information for the given request

Parameters
methodthe HTTP method (in lower case)
paththe URI path of the request
piothe PathItemObject corresponding to the URI path
swaggerthe schema object itself
rbodythe output example body value, if any
Returns
a RestExampleRequestInfo hash of example message information for the given request

◆ getExampleResponse()

hash<RestExampleResponseInfo> Swagger::OperationObject::getExampleResponse ( string  method,
string  path,
int  code,
reference  body 
)

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
bodythe output example body value, if any
Returns
a RestExampleResponseInfo hash giving example response message info

◆ getQoreExampleRequest()

hash<RestQoreExampleCodeInfo> Swagger::OperationObject::getQoreExampleRequest ( string  method,
string  path,
PathItemObject  pio,
SwaggerSchema  swagger 
)

returns example Qore code for the given request

Parameters
methodthe HTTP method (in lower case)
paththe URI path of the request
piothe PathItemObject corresponding to the URI path
swaggerthe schema object itself
Returns
a RestQoreExampleCodeInfo hash giving example Qore code to generate the given request message

◆ getQoreExampleResponse()

hash<RestQoreExampleCodeInfo> Swagger::OperationObject::getQoreExampleResponse ( string  method,
string  path,
int  code 
)

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

◆ getResponse()

*ResponseObject Swagger::OperationObject::getResponse ( int  code)
private

returns the ResponseObject for hthe given HTTP code or NOTHING if none is configured

Returns
the ResponseObject for hthe given HTTP code or NOTHING if none is configured

◆ parameters()

hash<string, AbstractParameterObject> Swagger::OperationObject::parameters ( )

A hash of parameters that are applicable for this operation.

If a parameter is already defined at the Path Item, the new definition will override it, but can never remove it. The hash MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a name and location. There can be one "body" parameter at most.

◆ parseRequest()

Swagger::OperationObject::parseRequest ( PathItemObject  pio,
reference< hash< UriQueryInfo >>  h,
reference< auto >  body,
reference< hash headers 
)

parses and processes a REST request on the server side

Parameters
piothe PathItemObject corresponding to the URI path
ha reference to the URI query info hash
bodya reference to the deserialized HTTP message body data
headersa reference to a hash of HTTP headers
Exceptions
DESERIALIZATION-ERRORinvalid content-type
INVALID-PARAMETER-NAMEinvalid parameter name
INVALID-PARAMETER-LOCATIONinvalid parameter location
MISSING-PARAMETERmissing parameter and parameter has no default value

◆ validateRequest()

Swagger::OperationObject::validateRequest ( bool  serialize,
PathItemObject  pio,
reference< hash< UriQueryInfo >>  h,
reference< auto >  body,
reference< hash headers,
*reference< hash< string, bool >>  mime_types 
)

processes a REST API client-side request to the operation

Parameters
serializeif request arguments should be processed for serialization (client-side) or not (server-side)
piothe PathItemObject corresponding to the URI path
ha reference to the URI query info hash
bodya reference to the deserialized HTTP message body data
headersa reference to a hash of HTTP headers
mime_typesa reference to a hash of valid mime types for the operation
Exceptions
SCHEMA-VALIDATION-ERRORinvalid parameter name or location, missing parameter and parameter has no default value

Member Data Documentation

◆ consumes

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

A list of MIME types (strings) the operation can consume.

This overrides the consumes definition at the Swagger Object. An empty value MAY be used to clear the global definition. Key values MUST be Mime Types.

◆ deprec

bool Swagger::OperationObject::deprec = False

Declares this operation to be deprecated.

Usage of the declared operation should be refrained. Default value is false.

◆ operationId

*string Swagger::OperationObject::operationId

Unique string used to identify the operation.

The id MUST be unique among all operations described in the API. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is recommended to follow common programming naming conventions.

◆ produces

hash<string, bool> Swagger::OperationObject::produces

A hash of MIME types (strings) the operation can produce.

This overrides the produces definition at the Swagger Object. An empty value MAY be used to clear the global definition. Key values MUST be Mime Types.

◆ schemes

list<string> Swagger::OperationObject::schemes

The transfer protocol for the operation.

Values MUST be from the list: "http", "https", "ws", "wss". The value overrides the SwaggerSchema schemes definition.

◆ security

list<hash<string, list<string> > > Swagger::OperationObject::security

A declaration of which security schemes are applied for this operation.

The list of values describes alternative security schemes that can be used (that is, there is a logical OR between the security requirements). This definition overrides any declared top-level security. To remove a top-level security declaration, an empty array can be used.

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.

◆ tags

list Swagger::OperationObject::tags

A list of tags (strings or TagObjects) for API documentation control.

Tags can be used for logical grouping of operations by resources or any other qualifier.