Class: Jsapi::Meta::Parameter::Base

Inherits:
Model::Base show all
Includes:
OpenAPI::Extensions
Defined in:
lib/jsapi/meta/parameter/base.rb

Overview

Specifies a parameter.

Constant Summary

Constants included from Model::Attributes

Model::Attributes::DEFAULT_ARRAY, Model::Attributes::DEFAULT_HASH

Instance Method Summary collapse

Methods included from OpenAPI::Extensions

included

Methods inherited from Model::Base

#inspect, #merge!, #reference?, #resolve

Methods included from Model::Attributes

#attribute, #attribute_names

Constructor Details

#initialize(name, keywords = {}) ⇒ Base

Creates a new parameter.

Raises an ArgumentError if name is blank.

Raises:

  • (ArgumentError) 


57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
 
# File 'lib/jsapi/meta/parameter/base.rb', line 57

def initialize(name, keywords = {})
  raise ArgumentError, "parameter name can't be blank" if name.blank?

  @name = name.to_s

  keywords = keywords.dup
  super(
    keywords.extract!(
      :content_type,
      :deprecated,
      :description,
      :examples,
      :in,
      :openapi_extensions
    )
  )
  add_example(value: keywords.delete(:example)) if keywords.key?(:example)
  keywords[:ref] = keywords.delete(:schema) if keywords.key?(:schema)

  @schema = Schema.new(keywords)
end

Instance Method Details

#allow_empty_value? ⇒ Boolean

Returns true if empty values are allowed as specified by OpenAPI, false otherwise.

Returns:

  • (Boolean) 


80
81
82
 
# File 'lib/jsapi/meta/parameter/base.rb', line 80

def allow_empty_value?
  schema.existence <= Existence::ALLOW_EMPTY && self.in == 'query'
end

#content_type ⇒ Object

:attr: content_type The media type used to describe complex parameters in OpenAPI 3.0 and higher.



15
 
# File 'lib/jsapi/meta/parameter/base.rb', line 15

attribute :content_type, String

#deprecated ⇒ Object

:attr: deprecated Specifies whether or not the parameter is deprecated.



20
 
# File 'lib/jsapi/meta/parameter/base.rb', line 20

attribute :deprecated, values: [true, false]

#description ⇒ Object

:attr: description The description of the parameter.



25
 
# File 'lib/jsapi/meta/parameter/base.rb', line 25

attribute :description, String

#examples ⇒ Object

:attr_reader: examples The examples.



30
 
# File 'lib/jsapi/meta/parameter/base.rb', line 30

attribute :examples, { String => Example }, default_key: 'default'

#in ⇒ Object

:attr: in The location of the parameter. Possible values are:

  • "header"

  • "path"

  • "query"

  • "querystring"

The default location is "query".



42
 
# File 'lib/jsapi/meta/parameter/base.rb', line 42

attribute :in, String, values: %w[header path query querystring], default: 'query'

#name ⇒ Object

:attr_reader: name The name of the parameter.



47
 
# File 'lib/jsapi/meta/parameter/base.rb', line 47

attribute :name, accessors: i[reader]

#required? ⇒ Boolean

Returns true if it is required as specified by JSON Schema, false otherwise.

Returns:

  • (Boolean) 


85
86
87
 
# File 'lib/jsapi/meta/parameter/base.rb', line 85

def required?
  schema.existence > Existence::ALLOW_OMITTED || self.in == 'path'
end

#schema ⇒ Object

:attr_reader: schema The Schema of the parameter.



52
 
# File 'lib/jsapi/meta/parameter/base.rb', line 52

attribute :schema, accessors: i[reader]

#to_openapi(version, definitions) ⇒ Object

Returns a hash representing the OpenAPI parameter object.



90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
 
# File 'lib/jsapi/meta/parameter/base.rb', line 90

def to_openapi(version, definitions)
  version = OpenAPI::Version.from(version)

  openapi_parameter_object(
    name,
    schema.resolve(definitions),
    version,
    location: self.in,
    content_type: content_type || ('text/plain' if self.in == 'querystring'),
    description: description,
    required: required?,
    deprecated: deprecated?,
    allow_empty_value: allow_empty_value?,
    examples: examples
  )
end

#to_openapi_parameters(version, definitions) ⇒ Object

Returns an array of hashes representing the OpenAPI parameter objects.



108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
 
# File 'lib/jsapi/meta/parameter/base.rb', line 108

def to_openapi_parameters(version, definitions)
  version = OpenAPI::Version.from(version)
  is_querystring = self.in == 'querystring'
  schema = self.schema.resolve(definitions)

  if schema.object? && (version < OpenAPI::V3_2 || !is_querystring)
    explode_parameter(
      is_querystring ? nil : name,
      schema,
      version,
      definitions,
      location: is_querystring ? 'query' : self.in,
      required: required?,
      deprecated: deprecated?
    )
  else
    [to_openapi(version, definitions)]
  end.compact
end