All Classes Namespaces Functions Variables Groups Pages
Swagger::OperationObject Class Reference

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

Inheritance diagram for Swagger::OperationObject:
[legend]

## Public Member Functions

| constructor (string path, string method, hash oh, SwaggerSchema swagger)
| Constructor. More...
hash < RestSchemaValidator::RestExampleRequestInfo > | getExampleRequest (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, AbstractParameterObject > | parameters ()
| 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 Functions 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
| the body parameter, if defined for this operation
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.
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< string > | schemes
| 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 Functions

| 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

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

Constructor.

Parameters

  path | the path for the operation
  method | the HTTP method for the operation
  oh | deserialized hash from the source schema description describing the operation
  swagger | the REST schema for resolving references

Exceptions

  INVALID-FIELD-TYPE | field has invalid type
  INVALID-FIELD-VALUE | field has invalid value
  REQUIRED-FIELD-MISSING | required field is missing

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

  method | the HTTP method (in lower case)
  path | the URI path of the request
  pio | the PathItemObject corresponding to the URI path
  swagger | the schema object itself
  rbody | the output example body value, if any

Returns
  a RestExampleRequestInfo hash of example message information for the given request

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

  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
  body | the output example body value, if any

Returns
  a RestExampleResponseInfo hash giving example response message info

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

returns example Qore code for the given request

Parameters

  method | the HTTP method (in lower case)
  path | the URI path of the request
  pio | the PathItemObject corresponding to the URI path
  swagger | the schema object itself

Returns
  a RestQoreExampleCodeInfo hash giving example Qore code to generate the given request message

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

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

*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

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.

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

  pio | the PathItemObject corresponding to the URI path
  h | a reference to the URI query info hash
  body | a reference to the deserialized HTTP message body data
  headers | a reference to a hash of HTTP headers

Exceptions

  DESERIALIZATION-ERROR | invalid content-type
  INVALID-PARAMETER-NAME | invalid parameter name
  INVALID-PARAMETER-LOCATION | invalid parameter location
  MISSING-PARAMETER | missing parameter and parameter has no default value

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

  serialize | if request arguments should be processed for serialization (client-side) or not (server-side)
  pio | the PathItemObject corresponding to the URI path
  h | a reference to the URI query info hash
  body | a reference to the deserialized HTTP message body data
  headers | a reference to a hash of HTTP headers
  mime_types | a reference to a hash of valid mime types for the operation

Exceptions

  SCHEMA-VALIDATION-ERROR | invalid parameter name or location, missing parameter and parameter has no default value

## Member Data Documentation

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.

bool Swagger::OperationObject::deprec = False

Declares this operation to be deprecated.

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

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

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.

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.

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.

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.