class Brainstem::ApiDocs::Sinks::OpenApiSpecificationSink

Constants

DEFAULT_API_VERSION
DEFAULT_FILENAME_PATTERN
DEFAULT_OAS_EXTENSION

Attributes

api_version[RW]
atlas[RW]
format[RW]
ignore_tagging[RW]
include_internal[RW]
oas_filename_pattern[RW]
output[RW]
output_extension[RW]
write_method[W]
write_path[W]

Public Instance Methods

<<(atlas) click to toggle source
# File lib/brainstem/api_docs/sinks/open_api_specification_sink.rb, line 41
def <<(atlas)
  self.atlas  = atlas
  self.output = ActiveSupport::HashWithIndifferentAccess.new

  write_info_object!
  write_presenter_definitions!
  write_error_definitions!
  write_endpoint_definitions!
  write_tag_definitions!
  write_security_definitions!

  write_spec_to_file!
end
valid_options() click to toggle source
# File lib/brainstem/api_docs/sinks/open_api_specification_sink.rb, line 14
def valid_options
  super | [
    :api_version,
    :ignore_tagging,
    :format,
    :write_method,
    :write_path,
    :oas_filename_pattern,
    :output_extension,
    :include_internal
  ]
end

Private Instance Methods

assert_directory_exists!(path) click to toggle source

Asserts that a directory exists, creating it if it does not.

# File lib/brainstem/api_docs/sinks/open_api_specification_sink.rb, line 188
def assert_directory_exists!(path)
  dir = File.dirname(path)
  FileUtils.mkdir_p(dir) unless File.directory?(dir)
end
extension() click to toggle source

Defines the file extension for the output file.

# File lib/brainstem/api_docs/sinks/open_api_specification_sink.rb, line 212
def extension
  return output_extension.downcase.to_s if output_extension.present?

  configured_extension = Brainstem::ApiDocs.output_extension.downcase.to_s
  configured_extension == "markdown" ? DEFAULT_OAS_EXTENSION : configured_extension
end
format_output(output, requested_format) click to toggle source

Format output to the requested format.

# File lib/brainstem/api_docs/sinks/open_api_specification_sink.rb, line 176
def format_output(output, requested_format)
  unless %w(json yaml yml).include?(requested_format)
    raise "Open API Specification only supports generation of json / yaml files"
  end

  data = output.to_hash
  requested_format == 'json' ? data.to_json : data.to_yaml
end
formatted_version() click to toggle source

Returns the version of the API.

# File lib/brainstem/api_docs/sinks/open_api_specification_sink.rb, line 65
def formatted_version
  self.api_version.presence || DEFAULT_API_VERSION
end
inject_objects_under_key!(top_level_key, objects, sort = false) click to toggle source

Sort hash by keys and add them to the output nested under the specified top level key

# File lib/brainstem/api_docs/sinks/open_api_specification_sink.rb, line 151
def inject_objects_under_key!(top_level_key, objects, sort = false)
  self.output[top_level_key] ||= {}

  ordered_keys = sort ? objects.keys.sort : objects.keys
  ordered_keys.each do |object_key|
    self.output[top_level_key][object_key] = objects[object_key]
  end

  self.output
end
suggested_filename() click to toggle source

Defines the name of the file.

# File lib/brainstem/api_docs/sinks/open_api_specification_sink.rb, line 225
def suggested_filename
  (oas_filename_pattern.presence || DEFAULT_FILENAME_PATTERN)
    .gsub('{{version}}', formatted_version)
    .gsub('{{extension}}', extension)
end
write_endpoint_definitions!() click to toggle source

Use the controller formatters to add endpoint definitions to the specification.

# File lib/brainstem/api_docs/sinks/open_api_specification_sink.rb, line 119
def write_endpoint_definitions!
  controller_definitions = controllers
    .formatted(format)
    .inject({}) do |definitions, path_definition|

    definitions.merge(path_definition)
  end

  inject_objects_under_key!(:paths, controller_definitions, true)
end
write_error_definitions!() click to toggle source

Add standard error structure to the definitions of the specification.

# File lib/brainstem/api_docs/sinks/open_api_specification_sink.rb, line 95
def write_error_definitions!
  self.output[:definitions].merge!(
    'Error' => {
      type: 'object',
      properties: {
        type:    type_and_format('string'),
        message: type_and_format('string')
      }
    },
    'Errors' => {
      type: 'object',
      properties: {
        errors: {
          type: 'array',
          items: { '$ref' => '#/definitions/Error' }
        }
      }
    }
  )
end
write_info_object!() click to toggle source

Use the Info formatter to get the swagger & info object.

# File lib/brainstem/api_docs/sinks/open_api_specification_sink.rb, line 72
def write_info_object!
  self.output.merge!(
    ::Brainstem::ApiDocs::FORMATTERS[:info][format].call(version: formatted_version)
  )
end
write_method() click to toggle source

Defines how we write out the files.

# File lib/brainstem/api_docs/sinks/open_api_specification_sink.rb, line 196
def write_method
  @write_method ||= Proc.new do |name, buff|
    File.write(name, buff, mode: 'w')
  end
end
write_path() click to toggle source

Defines the output directory for the file.

# File lib/brainstem/api_docs/sinks/open_api_specification_sink.rb, line 205
def write_path
  @write_path ||= ::Brainstem::ApiDocs.write_path
end
write_presenter_definitions!() click to toggle source

Use the presenter formatters to add schema definitions to the specification.

# File lib/brainstem/api_docs/sinks/open_api_specification_sink.rb, line 81
def write_presenter_definitions!
  presenter_definitions = presenters
    .formatted(format)
    .inject({}) do |definitions, object_with_definition|

    definitions.merge(object_with_definition)
  end

  inject_objects_under_key!(:definitions, presenter_definitions, true)
end
write_security_definitions!() click to toggle source

Use the Security Definitions formatter to get the security definitions & scopes.

# File lib/brainstem/api_docs/sinks/open_api_specification_sink.rb, line 142
def write_security_definitions!
  self.output.merge!(
    ::Brainstem::ApiDocs::FORMATTERS[:security][format].call
  )
end
write_spec_to_file!() click to toggle source

Writes a given bufer to a filename within the base path.

# File lib/brainstem/api_docs/sinks/open_api_specification_sink.rb, line 165
def write_spec_to_file!
  formatted_output = format_output(output, extension)
  abs_path         = File.join(write_path, suggested_filename)

  assert_directory_exists!(abs_path)
  write_method.call(abs_path, formatted_output)
end
write_tag_definitions!() click to toggle source

Use the controllers names as tag defintions

# File lib/brainstem/api_docs/sinks/open_api_specification_sink.rb, line 133
def write_tag_definitions!
  self.output.merge!(
    ::Brainstem::ApiDocs::FORMATTERS[:tags][format].call(controllers, ignore_tagging: self.ignore_tagging)
  )
end