Module: Brainstem::Concerns::ControllerDSL::ClassMethods
- Defined in:
- lib/brainstem/concerns/controller_dsl.rb
Instance Attribute Summary collapse
-
#brainstem_params_context ⇒ Object
In order to correctly scope the DSL, we must have a context under which keys are stored.
Instance Method Summary collapse
-
#actions(*axns, &block) ⇒ Object
Invokes
action
for each symbol in the argument list. -
#brainstem_params(&block) ⇒ Object
Container method that sets up base scoping for the configuration.
-
#consumes(*mime_types) ⇒ Object
Used only for Open API Specification generation.
-
#convert_to_proc(field_name_or_proc) ⇒ Proc
(also: #format_root_name)
Converts the field name into a Proc.
-
#deprecated(deprecated) ⇒ Object
Used only for Open API Specification generation.
-
#description(text, options = { nodoc: false, internal: false }) ⇒ Object
Specifies a low-level description of a particular context, usually (but not exclusively) reserved for methods.
-
#documented! ⇒ Object
Temporary implementation to track controllers that have been documented.
-
#dynamic_key_field(type, options = {}) ⇒ Object
Allows defining a field with a dynamic key either under a field block or the custom response block.
-
#dynamic_key_fields(type, options = {}, &block) ⇒ Object
Allows defining a field block with a dynamic key for a custom response.
-
#external_doc(doc_config) ⇒ Object
Used only for Open API Specification generation.
-
#field(name, type, options = {}) ⇒ Object
Allows defining a field either under a field block or the custom response block.
-
#fields(name, type, options = {}, &block) ⇒ Object
Allows defining a field block for a custom response.
-
#format_ancestry_options(field_name_proc, options = {}) ⇒ Object
Formats the ancestry options of the field.
-
#format_field_configuration(configuration_map, name, type, options = {}, &block) ⇒ Object
Formats the configuration of the param and returns the default configuration if not specified.
-
#format_root_ancestry_options(root_name) ⇒ Object
Formats the ancestry options of the field.
-
#internal!(description = true) ⇒ Object
Specifies that the scope should not be documented unless the ‘–include-internal` flag is passed in the CLI.
-
#model_params(root = Proc.new { |klass| klass.brainstem_model_name }, &block) ⇒ Object
Allows the bulk specification of
:root
options. -
#nodoc!(description = true) ⇒ Object
Specifies that the scope should not be documented.
-
#operation_id(unique_id) ⇒ Object
Used only for Open API Specification generation.
-
#presents(target_class = :default, options = { nodoc: false, internal: false }) ⇒ Object
Specifies which presenter is used for the controller / action.
-
#produces(*mime_types) ⇒ Object
Used only for Open API Specification generation.
- #reset_configuration! ⇒ Object
-
#response(type, options = {}, &block) ⇒ Object
Allows defining a custom response structure for an action.
-
#schemes(*schemes) ⇒ Object
Used only for Open API Specification generation.
-
#security(*schemes) ⇒ Object
Used only for Open API Specification generation.
-
#tag(tag_name) ⇒ Object
Used only for Open API Specification generation.
-
#tag_groups(*tag_group_names) ⇒ Object
Used only for Open API Specification generation.
-
#title(text, options = { nodoc: false, internal: false }) ⇒ Object
Specifies a title to be used in the description of a class.
-
#transform(transformations) ⇒ Object
(also: #transforms)
Adds a transform to the list of transforms.
-
#valid(name, type = nil, options = {}, &block) ⇒ Object
Adds a param to the list of valid params, storing the info sent with it.
-
#valid_dynamic_param(type, options = {}, &block) ⇒ Object
Adds a param that has a dynamic key to the list of valid params, storing the info sent with it.
Instance Attribute Details
#brainstem_params_context ⇒ Object
In order to correctly scope the DSL, we must have a context under which keys are stored. The default context is _default (to avoid any potential collisions with methods named ‘default’), and this context is used as the parent context for all other contexts.
The context will change, for example, when we are adding keys to the configuration for actions. In those cases, the context becomes the action_name
.
Any methods that change the context should change it back upon conclusion so that the assumption of consistent scope inside a block is possible.
44 45 46 |
# File 'lib/brainstem/concerns/controller_dsl.rb', line 44 def brainstem_params_context @brainstem_params_context end |
Instance Method Details
#actions(*axns, &block) ⇒ Object
Invokes action
for each symbol in the argument list. Used to specify shared configuration.
187 188 189 |
# File 'lib/brainstem/concerns/controller_dsl.rb', line 187 def actions(*axns, &block) axns.flatten.each { |name| action_context name, &block } end |
#brainstem_params(&block) ⇒ Object
Container method that sets up base scoping for the configuration.
49 50 51 52 53 |
# File 'lib/brainstem/concerns/controller_dsl.rb', line 49 def brainstem_params(&block) self.brainstem_params_context = DEFAULT_BRAINSTEM_PARAMS_CONTEXT class_eval(&block) self.brainstem_params_context = nil end |
#consumes(*mime_types) ⇒ Object
Used only for Open API Specification generation. #
A list of MIME types the endpoints can consume. This overrides the default consumes definition on the Info object in the Open API Specification.
377 378 379 |
# File 'lib/brainstem/concerns/controller_dsl.rb', line 377 def consumes(*mime_types) configuration[brainstem_params_context][:consumes] = mime_types.flatten end |
#convert_to_proc(field_name_or_proc) ⇒ Proc Also known as: format_root_name
Converts the field name into a Proc.
507 508 509 |
# File 'lib/brainstem/concerns/controller_dsl.rb', line 507 def convert_to_proc(field_name_or_proc) field_name_or_proc.respond_to?(:call) ? field_name_or_proc : Proc.new { field_name_or_proc.to_s } end |
#deprecated(deprecated) ⇒ Object
Used only for Open API Specification generation. #
Declares this operation to be deprecated. Usage of the declared operation should be refrained.
445 446 447 |
# File 'lib/brainstem/concerns/controller_dsl.rb', line 445 def deprecated(deprecated) configuration[brainstem_params_context][:deprecated] = deprecated end |
#description(text, options = { nodoc: false, internal: false }) ⇒ Object
Specifies a low-level description of a particular context, usually (but not exclusively) reserved for methods.
Setting the :nodoc
option marks this description as ‘internal use only’, and causes formatters not to display a description.
Setting the :internal
option marks this description as ‘internal use only’, and causes formatters not to display a description unless documentation is generated with ‘–include-internal` flag.
147 148 149 |
# File 'lib/brainstem/concerns/controller_dsl.rb', line 147 def description(text, = { nodoc: false, internal: false }) configuration[brainstem_params_context][:description] = .merge(info: text) end |
#documented! ⇒ Object
Temporary implementation to track controllers that have been documented.
58 59 60 |
# File 'lib/brainstem/concerns/controller_dsl.rb', line 58 def documented! configuration[brainstem_params_context][:documented] = true end |
#dynamic_key_field(type, options = {}) ⇒ Object
Allows defining a field with a dynamic key either under a field block or the custom response block.
346 347 348 |
# File 'lib/brainstem/concerns/controller_dsl.rb', line 346 def dynamic_key_field(type, = {}) field(DYNAMIC_KEY, type, ) end |
#dynamic_key_fields(type, options = {}, &block) ⇒ Object
Allows defining a field block with a dynamic key for a custom response
315 316 317 |
# File 'lib/brainstem/concerns/controller_dsl.rb', line 315 def dynamic_key_fields(type, = {}, &block) fields(DYNAMIC_KEY, type, , &block) end |
#external_doc(doc_config) ⇒ Object
Used only for Open API Specification generation. #
Additional external documentation for this operation. e.g {
"description": "Find more info here",
"url": "https://swagger.io"
}
420 421 422 |
# File 'lib/brainstem/concerns/controller_dsl.rb', line 420 def external_doc(doc_config) configuration[brainstem_params_context][:external_doc] = doc_config end |
#field(name, type, options = {}) ⇒ Object
Allows defining a field either under a field block or the custom response block.
329 330 331 332 333 334 335 |
# File 'lib/brainstem/concerns/controller_dsl.rb', line 329 def field(name, type, = {}) custom_response = configuration[brainstem_params_context][:custom_response] raise "`fields` must be nested under a response block" if custom_response.nil? formatted_name = convert_to_proc(name) custom_response[formatted_name] = format_field_configuration(custom_response, name, type, ) end |
#fields(name, type, options = {}, &block) ⇒ Object
Allows defining a field block for a custom response
295 296 297 298 299 300 301 302 303 304 |
# File 'lib/brainstem/concerns/controller_dsl.rb', line 295 def fields(name, type, = {}, &block) custom_response = configuration[brainstem_params_context][:custom_response] raise "`fields` must be nested under a response block" if custom_response.nil? formatted_name = convert_to_proc(name) field_block_config = format_field_configuration(custom_response, name, type, , &block) custom_response[formatted_name] = field_block_config ((formatted_name, field_block_config), &block) end |
#format_ancestry_options(field_name_proc, options = {}) ⇒ Object
Formats the ancestry options of the field. Returns a hash with ancestors.
525 526 527 528 529 530 |
# File 'lib/brainstem/concerns/controller_dsl.rb', line 525 def (field_name_proc, = {}) ancestors = [:ancestors].try(:dup) || [] ancestors << field_name_proc { ancestors: ancestors }.with_indifferent_access.reject { |_, v| v.blank? } end |
#format_field_configuration(configuration_map, name, type, options = {}, &block) ⇒ Object
Formats the configuration of the param and returns the default configuration if not specified.
535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 |
# File 'lib/brainstem/concerns/controller_dsl.rb', line 535 def format_field_configuration(configuration_map, name, type, = {}, &block) field_config = .with_indifferent_access field_config[:type] = type.to_s field_config[:dynamic_key] = true if name.present? && name.to_sym == DYNAMIC_KEY if .has_key?(:item_type) field_config[:item_type] = field_config[:item_type].to_s elsif field_config[:type] == 'array' field_config[:item_type] = block_given? ? 'hash' : 'string' end # Inherit `nodoc` attribute from parent parent_key = (field_config[:ancestors] || []).reverse.first if parent_key && (parent_field_config = configuration_map[parent_key]) field_config[:nodoc] ||= !!parent_field_config[:nodoc] end field_config.delete(:nested_levels) if field_config[:nested_levels].to_i < 2 DEFAULT_FIELD_CONFIG.merge(field_config).with_indifferent_access end |
#format_root_ancestry_options(root_name) ⇒ Object
Formats the ancestry options of the field. Returns a hash with ancestors & root.
515 516 517 518 519 520 |
# File 'lib/brainstem/concerns/controller_dsl.rb', line 515 def (root_name) root_proc = format_root_name(root_name) ancestors = [root_proc] { root: root_proc, ancestors: ancestors }.with_indifferent_access.reject { |_, v| v.blank? } end |
#internal!(description = true) ⇒ Object
Specifies that the scope should not be documented unless the ‘–include-internal` flag is passed in the CLI. Setting this on the default context will force the controller to be undocumented, whereas setting it within an action context will force that action to be undocumented.
78 79 80 |
# File 'lib/brainstem/concerns/controller_dsl.rb', line 78 def internal!(description = true) configuration[brainstem_params_context][:internal] = description end |
#model_params(root = Proc.new { |klass| klass.brainstem_model_name }, &block) ⇒ Object
Allows the bulk specification of :root
options. Useful for denoting parameters which are nested under a resource.
root
may be specified as a string or symbol, which will represent the final root key.
However, root
can also be specified as a Proc / callable object, in which case it is evaluated at format time, passed the controller constant. By default, if no argument is passed, it will return the controller’s brainstem_model_name
dynamically.
We provide this functionality as a way to handle parameter inheritance in subclasses where the brainstem_model_name may not be the same as the parent class.
210 211 212 |
# File 'lib/brainstem/concerns/controller_dsl.rb', line 210 def model_params(root = Proc.new { |klass| klass.brainstem_model_name }, &block) ((root), &block) end |
#nodoc!(description = true) ⇒ Object
Specifies that the scope should not be documented. Setting this on the default context will force the controller to be undocumented, whereas setting it within an action context will force that action to be undocumented.
68 69 70 |
# File 'lib/brainstem/concerns/controller_dsl.rb', line 68 def nodoc!(description = true) configuration[brainstem_params_context][:nodoc] = description end |
#operation_id(unique_id) ⇒ Object
Used only for Open API Specification generation. #
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 operation_id to uniquely identify an operation, therefore, it is recommended to follow common programming naming conventions.
360 361 362 363 364 365 366 |
# File 'lib/brainstem/concerns/controller_dsl.rb', line 360 def operation_id(unique_id) if brainstem_params_context == DEFAULT_BRAINSTEM_PARAMS_CONTEXT raise "`operation_id` is endpoint specific and cannot be defined on the controller" end configuration[brainstem_params_context][:operation_id] = unique_id end |
#presents(target_class = :default, options = { nodoc: false, internal: false }) ⇒ Object
Specifies which presenter is used for the controller / action. By default, expects presentation on all methods, and falls back to the class derived from brainstem_model_name
if a name is not given.
Setting the :nodoc
option marks this presenter as ‘internal use only’, and causes formatters to display this as not indicated.
Setting the :internal
option marks this presenter as ‘internal use only’, and causes formatters to not display this unless documentation is generated with ‘–include-internal` flag.
99 100 101 102 103 104 105 |
# File 'lib/brainstem/concerns/controller_dsl.rb', line 99 def presents(target_class = :default, = { nodoc: false, internal: false }) raise "`presents` must be a class (in #{self.to_s})" \ unless target_class.is_a?(Class) || target_class == :default || target_class.nil? target_class = brainstem_model_class if target_class == :default configuration[brainstem_params_context][:presents] = .merge(target_class: target_class) end |
#produces(*mime_types) ⇒ Object
Used only for Open API Specification generation. #
A list of MIME types the endpoints can produce. This overrides the default produces definition on the Info object in the Open API Specification.
390 391 392 |
# File 'lib/brainstem/concerns/controller_dsl.rb', line 390 def produces(*mime_types) configuration[brainstem_params_context][:produces] = mime_types.flatten end |
#reset_configuration! ⇒ Object
18 19 20 21 22 23 24 25 26 27 28 |
# File 'lib/brainstem/concerns/controller_dsl.rb', line 18 def reset_configuration! configuration.nest! :_default configuration[:_default].tap do |default| default.nest! :valid_params default.nest! :transforms default.nonheritable! :title default.nonheritable! :description default.nonheritable! :tag default.nonheritable! :tag_groups end end |
#response(type, options = {}, &block) ⇒ Object
Allows defining a custom response structure for an action.
271 272 273 274 275 276 277 278 279 280 281 282 283 |
# File 'lib/brainstem/concerns/controller_dsl.rb', line 271 def response(type, = {}, &block) configuration[brainstem_params_context].nest! :custom_response custom_response = configuration[brainstem_params_context][:custom_response] custom_response[:_config] = format_field_configuration( custom_response, nil, type, , &block ) class_eval(&block) if block_given? end |
#schemes(*schemes) ⇒ Object
Used only for Open API Specification generation. #
The transfer protocol for the operation. Values MUST be from the list: “http”, “https”, “ws”, “wss”. The value overrides the default schemes definition in the Info Object.
433 434 435 |
# File 'lib/brainstem/concerns/controller_dsl.rb', line 433 def schemes(*schemes) configuration[brainstem_params_context][:schemes] = schemes.flatten end |
#security(*schemes) ⇒ Object
Used only for Open API Specification generation. #
A declaration of which security schemes are applied for this operation. The list of values describes alternative security schemes that can be used. This definition overrides any declared top-level security. To remove a top-level security declaration, an empty array can be used.
404 405 406 |
# File 'lib/brainstem/concerns/controller_dsl.rb', line 404 def security(*schemes) configuration[brainstem_params_context][:security] = schemes.flatten end |
#tag(tag_name) ⇒ Object
Used only for Open API Specification generation. #
Specifies the tag name to be used in tagging a class.
159 160 161 162 163 164 165 |
# File 'lib/brainstem/concerns/controller_dsl.rb', line 159 def tag(tag_name) unless brainstem_params_context == DEFAULT_BRAINSTEM_PARAMS_CONTEXT raise "`tag` is not endpoint specific and is defined on the controller" end configuration[brainstem_params_context][:tag] = tag_name end |
#tag_groups(*tag_group_names) ⇒ Object
Used only for Open API Specification generation. #
Specifies an array of tag names to group the class under. Used for the x-tags OAS vendor extension.
175 176 177 178 179 180 181 |
# File 'lib/brainstem/concerns/controller_dsl.rb', line 175 def tag_groups(*tag_group_names) unless brainstem_params_context == DEFAULT_BRAINSTEM_PARAMS_CONTEXT raise "`tag_groups` is not endpoint specific and is defined on the controller" end configuration[brainstem_params_context][:tag_groups] = tag_group_names.flatten end |
#title(text, options = { nodoc: false, internal: false }) ⇒ Object
Specifies a title to be used in the description of a class. Can also be used for method section titles.
Setting the :nodoc
option marks this title as ‘internal use only’, and causes formatters to fall back to the controller constant or to the action name as appropriate. If you are trying to set the entire controller or action as nondocumentable, instead, use the .nodoc!
method in the desired context without a block.
Setting the :internal
option marks this title as ‘internal use only’, and causes formatters to fall back to the controller constant or to the action name as appropriate unless documentation is generated with ‘–include-internal` flag. If you are trying to set the entire controller or action as nondocumentable unless internal, instead, use the .internal!
method in the desired context without a block.
128 129 130 |
# File 'lib/brainstem/concerns/controller_dsl.rb', line 128 def title(text, = { nodoc: false, internal: false }) configuration[brainstem_params_context][:title] = .merge(info: text) end |
#transform(transformations) ⇒ Object Also known as: transforms
Adds a transform to the list of transforms. Used to rename incoming params to their internal names for usage.
461 462 463 464 465 466 |
# File 'lib/brainstem/concerns/controller_dsl.rb', line 461 def transform(transformations) transformations.each_pair do |k, v| transforms = configuration[brainstem_params_context][:transforms] transforms[k.to_sym] = v.to_sym end end |
#valid(name, type = nil, options = {}, &block) ⇒ Object
Adds a param to the list of valid params, storing the info sent with it.
231 232 233 234 235 236 237 238 239 |
# File 'lib/brainstem/concerns/controller_dsl.rb', line 231 def valid(name, type = nil, = {}, &block) valid_params = configuration[brainstem_params_context][:valid_params] param_config = format_field_configuration(valid_params, name, type, , &block) formatted_name = convert_to_proc(name) valid_params[formatted_name] = param_config ((formatted_name, param_config), &block) if block_given? end |
#valid_dynamic_param(type, options = {}, &block) ⇒ Object
Adds a param that has a dynamic key to the list of valid params, storing the info sent with it.
257 258 259 |
# File 'lib/brainstem/concerns/controller_dsl.rb', line 257 def valid_dynamic_param(type, = {}, &block) valid(DYNAMIC_KEY, type, , &block) end |