Module: Jsapi::Controller::Methods

Included in:
Base
Defined in:
lib/jsapi/controller/methods.rb

Instance Method Summary collapse

Instance Method Details

#api_definitions ⇒ Object

Returns the Meta::Definitions instance associated with the controller class. In particular, this method can be used to create an OpenAPI document, for example:

render(json: api_definitions.openapi_document)



11
12
13
 
# File 'lib/jsapi/controller/methods.rb', line 11

def api_definitions
  self.class.api_definitions
end

#api_operation(operation_name = nil, omit: nil, status: nil, strong: false, &block) ⇒ Object

Performs an API operation by calling the given block. The request parameters are passed as an instance of the operation’s model class to the block. The object returned by the block is implicitly rendered according to the appropriate response specification.

api_operation('foo') do |api_params|
  # ...
end

operation_name can be nil if the controller handles one operation only.

If :strong is true, parameters that can be mapped are accepted only. That means that the model passed to the block is invalid if there are any request parameters that can’t be mapped to a parameter or a request body property of the operation.

The :omit option specifies on which conditions properties are omitted in responses. Possible values are:

  • :empty - All of the properties whose value is empty are omitted.

  • :nil - All of the properties whose value is nil are omitted.

Raises an ArgumentError when :omit is other than :empty, :nil or nil.



37
38
39
40
41
42
43
44
45
46
47
48
49
50
 
# File 'lib/jsapi/controller/methods.rb', line 37

def api_operation(operation_name = nil,
                  omit: nil,
                  status: nil,
                  strong: false,
                  &block)
  _api_operation(
    operation_name,
    bang: false,
    omit: omit,
    status: status,
    strong: strong,
    &block
  )
end

#api_operation!(operation_name = nil, omit: nil, status: nil, strong: false, &block) ⇒ Object

Like api_operation, except that a ParametersInvalid exception is raised on invalid request parameters.

api_operation!('foo') do |api_params|
  # ...
end



59
60
61
62
63
64
65
66
67
68
69
70
71
72
 
# File 'lib/jsapi/controller/methods.rb', line 59

def api_operation!(operation_name = nil,
                   omit: nil,
                   status: nil,
                   strong: false,
                   &block)
  _api_operation(
    operation_name,
    bang: true,
    omit: omit,
    status: status,
    strong: strong,
    &block
  )
end

#api_params(operation_name = nil, strong: false) ⇒ Object

Returns the request parameters as an instance of the operation’s model class. Parameter names are converted to snake case.

params = api_params('foo')

operation_name can be nil if the controller handles one operation only.

If strong is true, parameters that can be mapped are accepted only. That means that the model returned is invalid if there are any request parameters that can’t be mapped to a parameter or a request body property of the operation.

Note that each call of api_params returns a newly created instance.



86
87
88
89
90
91
92
93
 
# File 'lib/jsapi/controller/methods.rb', line 86

def api_params(operation_name = nil, strong: false)
  definitions = api_definitions
  _api_params(
    _find_api_operation(operation_name, definitions),
    definitions,
    strong: strong
  )
end

#api_response(result, operation_name = nil, omit: nil, status: nil) ⇒ Object

Returns a Response to serialize the JSON representation of result according to the appropriate response specification.

render(json: api_response(bar, 'foo', status: 200))

operation_name can be nil if the controller handles one operation only.

The :omit option specifies on which conditions properties are omitted. Possible values are:

  • :empty - All of the properties whose value is empty are omitted.

  • :nil - All of the properties whose value is nil are omitted.

Raises an ArgumentError when :omit is other than :empty, :nil or nil.



109
110
111
112
113
114
115
 
# File 'lib/jsapi/controller/methods.rb', line 109

def api_response(result, operation_name = nil, omit: nil, status: nil)
  definitions = api_definitions
  operation = _find_api_operation(operation_name, definitions)
  response_model = _api_response(operation, status, definitions)

  Response.new(result, response_model, api_definitions, omit: omit)
end