module SwaggerYard

config() click to toggle source

# File lib/swagger_yard.rb, line 40
def config
  @configuration ||= Configuration.new
end

configure() { |config| ... } click to toggle source

Configuration for Swagger Yard, use like:

SwaggerYard.configure do |config|
  config.swagger_version = "1.1"
  config.api_version = "0.1"
  config.doc_base_path = "http://swagger.example.com/doc"
  config.api_base_path = "http://swagger.example.com/api"
  config.reload = true # Rails.env.development?
end

# File lib/swagger_yard.rb, line 36
def configure
  yield config
end

log() click to toggle source

# File lib/swagger_yard.rb, line 44
def log
  YARD::Logger.instance
end

register_custom_yard_tags!() click to toggle source

Register some custom yard tags used by swagger-ui

# File lib/swagger_yard.rb, line 103
def register_custom_yard_tags!
  ::YARD::Tags::Library.define_tag("Api resource", :resource)
  ::YARD::Tags::Library.define_tag("Api path", :path, :with_types)
  ::YARD::Tags::Library.define_tag("Parameter", :parameter, :with_types_name_and_default)
  ::YARD::Tags::Library.define_tag("Response type", :response_type, :with_types)
  ::YARD::Tags::Library.define_tag("Error response message", :error_message, :with_types_and_name)
  ::YARD::Tags::Library.define_tag("Response", :response, :with_types_and_name)
  ::YARD::Tags::Library.define_tag("Api Summary", :summary)
  ::YARD::Tags::Library.define_tag("Model resource", :model)
  ::YARD::Tags::Library.define_tag("Model superclass", :inherits)
  ::YARD::Tags::Library.define_tag("Model property", :property, :with_types_name_and_default)
  ::YARD::Tags::Library.define_tag("Model discriminator", :discriminator, :with_types_name_and_default)
  ::YARD::Tags::Library.define_tag("Additional properties", :additional_properties)
  ::YARD::Tags::Library.define_tag("Authorization", :authorization, :with_types_and_name)
  ::YARD::Tags::Library.define_tag("Authorization Use", :authorize_with)
  # @example is a core YARD tag, let's use it
  # ::YARD::Tags::Library.define_tag("Example", :example, :with_title_and_text)
  ::YARD::Tags::Library.define_directive(:model, :with_title_and_text, Directives::ParamClassDirective)
end

requires_attrs(tag, *attrs) click to toggle source

Validates that the tag has non-nil values for the given attribute methods. Logs a warning message and returns nil if the tag is not valid.

# File lib/swagger_yard.rb, line 50
def requires_attrs(tag, *attrs)
  valid = true
  attrs.each do |a|
    valid &&= tag.send(a)
    break unless valid
  end
  unless valid
    if tag.object
      object   = " in #{tag.object.to_s}"
      location = " near #{tag.object.files.first.join(':')}" if tag.object.files.first
    end
    log.warn "invalid @#{tag.tag_name} tag#{object}#{location}"
    return nil
  end
  tag
end

requires_name(tag) click to toggle source

# File lib/swagger_yard.rb, line 67
def requires_name(tag)
  requires_attrs(tag, :name)
end

requires_name_and_type(tag) click to toggle source

# File lib/swagger_yard.rb, line 71
def requires_name_and_type(tag)
  requires_attrs(tag, :name, :types)
end

requires_type(tag) click to toggle source

# File lib/swagger_yard.rb, line 75
def requires_type(tag)
  requires_attrs(tag, :types)
end

yard_class_objects_from_file(file_path) click to toggle source

Parse all objects in the file and return the class objects found.

@param file_path [string] The complete path to file @return [YARD] objects representing classes from the file

# File lib/swagger_yard.rb, line 97
def yard_class_objects_from_file(file_path)
  yard_objects_from_file(file_path, :class)
end

yard_objects_from_file(file_path, *types) click to toggle source

Use YARD to parse object tags from a file

@param file_path [string] The complete path to file @param types additional types by which to filter the result (:class/:module/:method) @return [YARD] objects representing class/methods and tags from the file

# File lib/swagger_yard.rb, line 86
def yard_objects_from_file(file_path, *types)
  ::YARD.parse(file_path)
  ::YARD::Registry.all(*types).select {|co| co.file == file_path }
end

Constants

Public Class Methods