swagger_yard 0.0.5 → 0.1.0

data/lib/swagger_yard/model.rb

@@ -0,0 +1,69 @@
+module SwaggerYard
+  #
+  # Carries id (the class name) and properties for a referenced
+  #   complex model object as defined by swagger schema
+  #
+  class Model
+    attr_reader :id
+
+    def self.from_yard_objects(yard_objects)
+      from_yard_object(yard_objects.detect {|o| o.type == :class })
+    end
+
+    def self.from_yard_object(yard_object)
+      from_tags(yard_object.tags) if yard_object
+    end
+
+    def self.from_tags(tags)
+      new.tap do |model|
+        model.parse_tags(tags)
+      end
+    end
+
+    def initialize
+      @properties = []
+    end
+
+    def valid?
+      !id.nil?
+    end
+
+    def parse_tags(tags)
+      tags.each do |tag|
+        case tag.tag_name
+        when "model"
+          @id = tag.text
+        when "property"
+          @properties << Property.from_tag(tag)
+        end
+      end
+
+      self
+    end
+
+    def properties_model_names
+      @properties.map(&:model_name).compact
+    end
+
+    def recursive_properties_model_names(model_list)
+      properties_model_names + properties_model_names.map do |model_name|
+        child_model = model_from_model_list(model_list, model_name)
+        child_model.recursive_properties_model_names(model_list) if child_model
+      end.compact
+    end
+
+    def model_from_model_list(model_list, model_name)
+      model_list.find{|model| model.id == model_name}
+    end
+
+    def to_h
+      raise "Model is missing @model tag" if id.nil?
+
+      {
+        "id" => id,
+        "properties" => Hash[@properties.map {|property| [property.name, property.to_h]}],
+        "required" => @properties.select(&:required?).map(&:name)
+      }
+    end
+  end
+end

data/lib/swagger_yard/operation.rb

@@ -0,0 +1,149 @@
+module SwaggerYard
+  class Operation
+    attr_accessor :summary, :notes
+    attr_reader :path, :http_method, :error_messages, :response_type
+    attr_reader :parameters, :model_names
+
+    PARAMETER_LIST_REGEX = /\A\[(\w*)\]\s*(\w*)(\(required\))?\s*(.*)\n([.\s\S]*)\Z/
+
+    # TODO: extract to operation builder?
+    def self.from_yard_object(yard_object, api)
+      new(api).tap do |operation|
+        yard_object.tags.each do |tag|
+          case tag.tag_name
+          when "path"
+            operation.add_path_params_and_method(tag)
+          when "parameter"
+            operation.add_parameter(tag)
+          when "parameter_list"
+            operation.add_parameter_list(tag)
+          when "response_type"
+            operation.add_response_type(Type.from_type_list(tag.types))
+          when "error_message"
+            operation.add_error_message(tag)
+          when "summary"
+            operation.summary = tag.text
+          when "notes"
+            operation.notes = tag.text.gsub("\n", "<br\>")
+          end
+        end
+
+        operation.sort_parameters
+        operation.append_format_parameter
+      end
+    end
+
+    def initialize(api)
+      @api = api
+      @parameters = []
+      @model_names = []
+      @error_messages = []
+    end
+
+    def nickname
+      @path[1..-1].gsub(/[^a-zA-Z\d:]/, '-').squeeze("-") + http_method.downcase
+    end
+
+    def to_h
+      {
+        "httpMethod"        => http_method,
+        "nickname"          => nickname,
+        "type"              => "void",
+        "produces"          => ["application/json", "application/xml"],
+        "parameters"        => parameters.map(&:to_h),
+        "summary"           => summary || @api.description,
+        "notes"             => notes,
+        "responseMessages"  => error_messages
+      }.tap do |h|
+        h.merge!(response_type.to_h) if response_type
+      end
+    end
+
+    ##
+    # Example: [GET] /api/v2/ownerships.{format_type}
+    # Example: [PUT] /api/v1/accounts/{account_id}.{format_type}
+    def add_path_params_and_method(tag)
+      @path = tag.text
+      @http_method = tag.types.first
+
+      parse_path_params(tag.text).each do |name|
+        @parameters << Parameter.from_path_param(name)
+      end
+    end
+
+    ##
+    # Example: [Array]     status            Filter by status. (e.g. status[]=1&status[]=2&status[]=3)
+    # Example: [Array]     status(required)  Filter by status. (e.g. status[]=1&status[]=2&status[]=3)
+    # Example: [Array]     status(required, body)  Filter by status. (e.g. status[]=1&status[]=2&status[]=3)
+    # Example: [Integer]   media[media_type_id]                          ID of the desired media type.
+    def add_parameter(tag)
+      @parameters << Parameter.from_yard_tag(tag, self)
+    end
+
+    ##
+    # Example: [String]    sort_order  Orders ownerships by fields. (e.g. sort_order=created_at)
+    #          [List]      id              
+    #          [List]      begin_at        
+    #          [List]      end_at          
+    #          [List]      created_at      
+    def add_parameter_list(tag)
+      # TODO: switch to using Parameter.from_yard_tag
+      data_type, name, required, description, list_string = parse_parameter_list(tag)
+      allowable_values = parse_list_values(list_string)
+
+      @parameters << Parameter.new(name, Type.new(data_type.downcase), description, {
+        required: !!required,
+        param_type: "query",
+        allow_multiple: false,
+        allowable_values: allowable_values
+      })
+    end
+
+    def add_response_type(type)
+      model_names << type.model_name
+      @response_type = type
+    end
+
+    def add_error_message(tag)
+      @error_messages << {
+        "code" => Integer(tag.name),
+        "message" => tag.text,
+        "responseModel" => Array(tag.types).first
+      }.reject {|_,v| v.nil?}
+    end
+
+    def sort_parameters
+      @parameters.sort_by! {|p| p.name}
+    end
+
+    def append_format_parameter
+      @parameters << format_parameter
+    end
+
+    def ref?(data_type)
+      @api.ref?(data_type)
+    end
+
+    private
+    def parse_path_params(path)
+      path.scan(/\{([^\}]+)\}/).flatten.reject { |value| value == "format_type" }
+    end
+
+    def parse_parameter_list(tag)
+      tag.text.match(PARAMETER_LIST_REGEX).captures
+    end
+
+    def parse_list_values(list_string)
+      list_string.split("[List]").map(&:strip).reject { |string| string.empty? }
+    end
+
+    def format_parameter
+      Parameter.new("format_type", Type.new("string"), "Response format either JSON or XML", {
+        required: true,
+        param_type: "path",
+        allow_multiple: false,
+        allowable_values: ["json", "xml"]
+      })
+    end
+  end
+end

data/lib/swagger_yard/parameter.rb

@@ -1,9 +1,68 @@
 module SwaggerYard
   class Parameter
-    attr_accessor :param_type, :name, :description, :data_type, :required, :allow_multiple, :allowable_values
+    attr_accessor :name, :description
+    attr_reader :param_type, :required, :allow_multiple, :allowable_values
 
-    def initialize(yard_object)
-      
+    def self.from_yard_tag(tag, operation)
+      description = tag.text
+      name, options_string = tag.name.split(/[\(\)]/)
+      type = Type.from_type_list(tag.types)
+
+      options = {}
+
+      operation.model_names << type.name if type.ref?
+
+      unless options_string.nil?
+        options_string.split(',').map(&:strip).tap do |arr|
+          options[:required] = !arr.delete('required').nil?
+          options[:allow_multiple] = !arr.delete('multiple').nil?
+          options[:param_type] = arr.last
+        end
+      end
+
+      new(name, type, description, options)
+    end
+
+    # TODO: support more variation in scope types
+    def self.from_path_param(name)
+      new(name, Type.new("string"), "Scope response to #{name}", {
+        required: true,
+        allow_multiple: false,
+        param_type: "path"
+      })
+    end
+
+    def initialize(name, type, description, options={})
+      @name, @type, @description = name, type, description
+
+      @required = options[:required] || false
+      @param_type = options[:param_type] || 'query'
+      @allow_multiple = options[:allow_multiple] || false
+      @allowable_values = options[:allowable_values] || []
+    end
+
+    def type
+      @type.name
+    end
+
+    def allowable_values_hash
+      return nil if allowable_values.empty?
+
+      {
+        "valueType" => "LIST",
+        "values" => allowable_values
+      }
+    end
+
+    def to_h
+      {
+        "paramType"       => param_type,
+        "name"            => name,
+        "description"     => description,
+        "required"        => required,
+        "allowMultiple"   => !!allow_multiple,
+        "allowableValues" => allowable_values_hash 
+      }.merge(@type.to_h).reject {|k,v| v.nil?}
     end
   end
 end

data/lib/swagger_yard/property.rb

@@ -0,0 +1,36 @@
+module SwaggerYard
+  #
+  # Holds the name and type for a single model property
+  #
+  class Property
+    attr_reader :name, :description
+
+    def self.from_tag(tag)
+      name, options_string = tag.name.split(/[\(\)]/)
+
+      required = options_string.to_s.split(',').map(&:strip).include?('required')
+
+      new(name, tag.types, tag.text, required)
+    end
+
+    def initialize(name, types, description, required)
+      @name, @description, @required = name, description, required
+
+      @type = Type.from_type_list(types)
+    end
+
+    def required?
+      @required
+    end
+
+    def model_name
+      @type.model_name
+    end
+
+    def to_h
+      result = @type.to_h
+      result["description"] = description if description
+      result
+    end
+  end
+end

data/lib/swagger_yard/resource_listing.rb

@@ -1,32 +1,71 @@
 module SwaggerYard
   class ResourceListing
-    attr_reader :api_declarations
+    attr_reader :api_declarations, :resource_to_file_path
+    attr_accessor :authorizations
 
-    def initialize
-      @api_declarations = []
+    def initialize(controller_path, model_path)
+      @model_path = model_path
+      @controller_path = controller_path
+
+      @resource_to_file_path = {}
+      @authorizations = []
+    end
+
+    def models
+      @models ||= parse_models
+    end
+
+    def controllers
+      @controllers ||= parse_controllers
     end
 
-    def add(api_declaration)
-      @api_declarations << api_declaration
+    def declaration_for(resource_name)
+      controllers[resource_name]
     end
 
     def to_h
-      { 
-        "apiVersion"     => SwaggerYard.api_version,
-        "swaggerVersion" => SwaggerYard.swagger_version,
-        "basePath"       => SwaggerYard.doc_base_path,
-        "apis"           => list_api
+      {
+        "apiVersion"      => SwaggerYard.config.api_version,
+        "swaggerVersion"  => SwaggerYard.config.swagger_version,
+        "basePath"        => SwaggerYard.config.swagger_spec_base_path,
+        "apis"            => list_api_declarations,
+        "authorizations"  => authorizations_hash
       }
     end
 
   private
-    def list_api
-      @api_declarations.map do |api_declaration|
-        {
-          "path"        => api_declaration.resource_path,
-          "description" => api_declaration.description
-        }
-      end.sort_by { |hsh| hsh["path"] }
+    def list_api_declarations
+      controllers.values.sort_by(&:resource_path).map(&:listing_hash)
+    end
+
+    def parse_models
+      return [] unless @model_path
+
+      Dir[@model_path].map do |file_path|
+        Model.from_yard_objects(SwaggerYard.yard_objects_from_file(file_path))
+      end.compact.select(&:valid?)
+    end
+
+    def parse_controllers
+      return {} unless @controller_path
+
+      Hash[Dir[@controller_path].map do |file_path|
+        declaration = create_api_declaration(file_path)
+
+        [declaration.resource_name, declaration] if declaration.valid?
+      end.compact]
+    end
+
+    def create_api_declaration(file_path)
+      yard_objects = SwaggerYard.yard_objects_from_file(file_path)
+
+      ApiDeclaration.new(self).add_yard_objects(yard_objects)
+    end
+
+    def authorizations_hash
+      Hash[
+        authorizations.map(&:name).zip(authorizations.map(&:to_h)) # ugh
+      ]
     end
   end
-end
+end

data/lib/swagger_yard/type.rb

@@ -0,0 +1,34 @@
+module SwaggerYard
+  class Type
+    def self.from_type_list(types)
+      parts = types.first.split(/[<>]/)
+      new(parts.last, parts.grep(/array/i).any?)
+    end
+
+    attr_reader :name, :array
+
+    def initialize(name, array=false)
+      @name, @array = name, array
+    end
+
+    # TODO: have this look at resource listing?
+    def ref?
+      /[[:upper:]]/.match(name)
+    end
+
+    def model_name
+      ref? ? name : nil
+    end
+
+    alias :array? :array
+
+    def to_h
+      type_tag = ref? ? "$ref" : "type"
+      if array?
+        {"type"=>"array", "items"=> { type_tag => name }}
+      else
+        {"type"=>name}
+      end
+    end
+  end
+end

data/lib/swagger_yard/version.rb

@@ -1,3 +1,3 @@
 module SwaggerYard
-  VERSION = "0.0.5"
+  VERSION = "0.1.0"
 end

data/lib/swagger_yard.rb

@@ -1,7 +1,16 @@
 require "yard"
-require "swagger_yard/engine"
-require "swagger_yard/cache"
-require "swagger_yard/parser"
+require "json"
+require "swagger_yard/configuration"
+require "swagger_yard/type"
+require "swagger_yard/parameter"
+require "swagger_yard/property"
+require "swagger_yard/operation"
+require "swagger_yard/authorization"
+require "swagger_yard/resource_listing"
+require "swagger_yard/api_declaration"
+require "swagger_yard/model"
+require "swagger_yard/api"
+require "swagger_yard/listing_info"
 
 module SwaggerYard
   class << self
@@ -13,101 +22,49 @@ module SwaggerYard
     #     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
     def configure
-      yield self
+      yield config
     end
 
-    attr_accessor :doc_base_path, :api_base_path, :api_path
-    attr_writer :swagger_version, :api_version, :cache_store, :cache_prefix, :enable, :reload
-
-    def cache_store
-      @cache_store ||= Rails.cache
-    end
-    
-    def cache_prefix
-      @cache_prefix ||= "swagger_yard/"
-    end
-
-    def swagger_version
-      @swagger_version ||= "1.1"
+    def config
+      @configuration ||= Configuration.new
     end
 
-    def api_version
-      @api_version ||= "0.1"
-    end
-
-    def enable
-      @enable ||= false
-    end
-
-    def reload
-      @reload ||= false
-    end
-
-    def resource_to_file_path
-      @resource_to_file_path ||= {}
-    end
-
-    def parse_file(file_path)
-      ::YARD.parse(file_path)
-      yard_objects = ::YARD::Registry.all
+    #
+    # Use YARD to parse object tags from a file
+    # 
+    # @param file_path [string] The complete path to file
+    # @return [YARD] objects representing class/methods and tags from the file
+    # 
+    def yard_objects_from_file(file_path)
       ::YARD::Registry.clear
-      @parser.run(yard_objects)
-    end
-
-    def generate!(controller_path)
-      register_custom_yard_tags!
-      @controller_path = controller_path
-      cache.fetch("listing_index") { parse_controllers }
-    end
-
-    def get_api(resource_name)
-      if reload
-        parse_file(resource_to_file_path[resource_name]).to_h
-      else
-        cache.fetch(resource_name) { parse_file(resource_to_file_path[resource_name]).to_h }
-      end
+      ::YARD.parse(file_path)
+      ::YARD::Registry.all
     end
 
-    def get_listing
-      if reload
-        parse_controllers
-      else
-        cache.fetch("listing_index") { parse_controllers }
-      end
+    def yard_objects_from_resource(resource_name)
+      yard_objects_from_file(resource_to_file_path[resource_name])
     end
 
-  private
     ##
     # Register some custom yard tags used by swagger-ui
     def register_custom_yard_tags!
       ::YARD::Tags::Library.define_tag("Api resource", :resource)
       ::YARD::Tags::Library.define_tag("Resource path", :resource_path)
-      ::YARD::Tags::Library.define_tag("Api path", :path)
-      ::YARD::Tags::Library.define_tag("Parameter", :parameter)
+      ::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("Parameter list", :parameter_list)
       ::YARD::Tags::Library.define_tag("Status code", :status_code)
       ::YARD::Tags::Library.define_tag("Implementation notes", :notes)
-      ::YARD::Tags::Library.define_tag("Response class", :response_class)
+      ::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("Api Summary", :summary)
-    end
-
-    def cache
-      @cache ||= Cache.new(cache_store, cache_prefix)
-    end
-
-    def parse_controllers
-      @parser = Parser.new
-
-      Dir[@controller_path].each do |file|
-        if api_declaration = parse_file(file)
-          resource_to_file_path[api_declaration.resource_name] = file
-          cache[api_declaration.resource_name] = api_declaration.to_h
-        end
-      end
-
-      @parser.listing.to_h
+      ::YARD::Tags::Library.define_tag("Model resource", :model)
+      ::YARD::Tags::Library.define_tag("Model property", :property, :with_types_name_and_default)
+      ::YARD::Tags::Library.define_tag("Authorization", :authorization, :with_types_and_name)
+      ::YARD::Tags::Library.define_tag("Authorization Use", :authorize_with)
     end
   end
 end