| Qore Swagger Module Reference 2.2.3

Loading...
Searching...
No Matches
Public Member Functions | Public Attributes | Protected Member Functions | List of all members
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< auto > oh, SwaggerSchema swagger)
| Constructor.
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
hash< RestExampleResponseInfo > | getExampleResponse (string method, string path, int code, reference< auto > body)
| returns a hash of example message information for the given request
hash< RestQoreExampleCodeInfo > | getQoreExampleRequest (string method, string path, PathItemObject pio, SwaggerSchema swagger)
| returns example Qore code for the given request
hash< RestQoreExampleCodeInfo > | getQoreExampleResponse (string method, string path, int code)
| returns example Qore code for the given response
*data | getRequestBody (PathItemObject pio, auto body, reference< hash< auto > > headers, *bool freeform)
| Processes a generated request.
| parseRequest (PathItemObject pio, reference< hash< UriQueryInfo > > h, reference< auto > body, reference< hash > headers)
| parses and processes a REST request on the server side
| validateRequest (bool serialize, PathItemObject pio, reference< hash< UriQueryInfo > > h, reference< auto > body, reference< hash > headers, *reference< hash< string, bool > > mime_types, *bool freeform)
| processes a REST API client-side request to the operation
| validateResponse (string method, string path, PathItemObject pio, int http_code, reference< auto > response_body, reference< hash< string, bool > > mime_types, bool deserialize=True)
| validates a response against the response definition, if any
Public Member Functions inherited from Swagger::ParameterGroup
| addParameter (AbstractParameterObject p)
| Adds a parameter to the group.
| addParameter (string key, AbstractParameterObject p)
| Adds a parameter to the group.
| constructor (hash< auto > oh)
| Creates the object from the hash definition.
hash< string, AbstractParameterObject > | parameters ()
| A hash of parameters for this object.
Public Member Functions inherited from Swagger::ObjectBase
| constructor ()
| Constructor.
| constructor (hash< auto > oh)
| Constructor.
| constructor (ObjectBase other)
| copy constructor
| initialize (hash< auto > oh)
| Initialize.

## Public Attributes
AbstractParameterObject | body
| The body parameter, if defined.
hash< string, bool > | consumes
| A list of MIME types (strings) the operation can consume.
bool | deprec = False
| Declares this operation to be deprecated.
*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.
hash< string, 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.
string | path
| the URI path for the operation
hash< string, bool > | produces
| A hash of MIME types (strings) the operation can produce.
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.
list< hash< string, list< string > > > | security
| A declaration of which security schemes are applied for this operation.
*string | summary
| A short summary of what the operation does.
list | tags
| A list of tags (strings or TagObjects) for API documentation control.
Public Attributes inherited from Swagger::ParameterGroup
string | query_obj
| Any query param with type "object"? (OpenAPI 3 compatible)
Public Attributes inherited from Swagger::ObjectBase
hash< auto > | vendorExtensions
| Allows extensions to the Swagger Schema.

## Protected Member Functions
| checkMissingParams (hash< UriQueryInfo > h, *hash< auto > 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

## Detailed Description

Describes a single API operation on a path.

## Member Function Documentation

## ◆ constructor()

Swagger::OperationObject::constructor | ( | string | path,
|  | string | method,
|  | hash< auto > | 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

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

  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

## ◆ getExampleResponse()

hash< RestExampleResponseInfo > Swagger::OperationObject::getExampleResponse | ( | string | method,
|  | string | path,
|  | int | code,
|  | reference< auto > | 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

## ◆ getQoreExampleRequest()

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

## ◆ getQoreExampleResponse()

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

## ◆ getResponse()

*ResponseObject Swagger::OperationObject::getResponse | ( | int | code | ) |
| protected

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

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

  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

## ◆ validateRequest()

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

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
  freeform | do not validate types

Exceptions

  SCHEMA-VALIDATION-ERROR | invalid 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.