swagger-doc-rails 1.0.0

data/Rakefile

@@ -0,0 +1,10 @@
+require "rubygems"
+require 'appraisal'
+require "bundler/setup"
+require "bundler/gem_tasks"
+
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+task :default => :spec
+task :test => :spec

data/certs/gem-public_cert.pem

@@ -0,0 +1,21 @@
+-----BEGIN CERTIFICATE-----
+MIIDeDCCAmCgAwIBAgIBATANBgkqhkiG9w0BAQUFADBBMRMwEQYDVQQDDApyaWNo
+aG9sbGlzMRUwEwYKCZImiZPyLGQBGRYFZ21haWwxEzARBgoJkiaJk/IsZAEZFgNj
+b20wHhcNMTMxMDIyMTMwMzI3WhcNMTQxMDIyMTMwMzI3WjBBMRMwEQYDVQQDDApy
+aWNoaG9sbGlzMRUwEwYKCZImiZPyLGQBGRYFZ21haWwxEzARBgoJkiaJk/IsZAEZ
+FgNjb20wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDppQTU++yinAuC
+ydu87c/vDGTmE5Go9/zI48/T0kTco+JbUn4BPUaK0DWCEpZULvqwQAqVQm8JQnIU
+6Z3k1tAQbhtgbG2oWNIxyC7SyXMQw/ag5qoAhw6k3DFE+jGKrREzADFb7vG+nPYp
+4yinx27jCTIAv7/z2AVt6HoHOYh1s0HniJQWCebi7QgNXboMY8MpFxSwNkcFjl14
+KMSf9SX7iOyiwqgcJmN0fN4be8pH5j/EdinUL1rWlwldcUo2+6LChBswRPmtdaZv
+UyICuX5VfVJA0KrA/ihIMLaZVO5esFso+YrpP+QgbvhLwhn5e/sB5dr3a+y0+GJZ
+zPGtm60bAgMBAAGjezB5MAkGA1UdEwQCMAAwCwYDVR0PBAQDAgSwMB0GA1UdDgQW
+BBShIiKLL1E1JG++RUVAOSPO7rZV0TAfBgNVHREEGDAWgRRyaWNoaG9sbGlzQGdt
+YWlsLmNvbTAfBgNVHRIEGDAWgRRyaWNoaG9sbGlzQGdtYWlsLmNvbTANBgkqhkiG
+9w0BAQUFAAOCAQEAe4P1TzJlVhUn60Wx/431wNnuHZS9K4gSzmNr4zuZU6lP3rxx
+rMsSY1nJY1nTBqX9W62hO+KS14ncbZvNU59ao5YVXHDflEB3Yz20DP9E2Uws64Bx
+ify0Dwuq4VV2PiQbczuTGhGupzQpkMttWNZqVdjDbH5k8sGx3MumNX7YUJwUerhZ
+bTBme5soNyJzAeWBqCBPT9p98rC6vqhcBfAVF6RbERYL6MPyoBZWqGeuMR4H2X/v
+RYcsqDfanYBx7QcftOnbeQq7/Ep7Zx+W9+Ph3TiJLMLdAr7bLkgN1SjvrjTL5mQR
+FuQtYvE4LKiUQpG7vLTRB78dQBlSj9fnv2OM9w==
+-----END CERTIFICATE-----

data/lib/swagger/docs.rb

@@ -0,0 +1,14 @@
+require "swagger/docs/config"
+require "swagger/docs/dsl"
+require "swagger/docs/api_declaration_file_metadata"
+require "swagger/docs/api_declaration_file"
+require "swagger/docs/generator"
+require "swagger/docs/impotent_methods"
+require "swagger/docs/methods"
+require "swagger/docs/task"
+require "swagger/docs/version"
+
+module Swagger
+  module Docs
+  end
+end

data/lib/swagger/docs/api_declaration_file.rb

@@ -0,0 +1,125 @@
+module Swagger
+  module Docs
+    class ApiDeclarationFile
+      attr_reader :metadata, :apis
+
+      def initialize(metadata, apis, models)
+        @metadata = metadata
+        @apis = camelize_keys_deep apis
+        @models = models
+      end
+
+      def generate_resource
+        resource = build_resource_root_hash
+        # Add the already-normalized models to the resource.
+        resource = resource.merge({:models => models}) if models.present?
+        resource
+      end
+
+      def base_path
+        metadata.base_path
+      end
+
+      def path
+        metadata.path
+      end
+
+      def swagger_version
+        metadata.swagger_version
+      end
+
+      def api_version
+        metadata.api_version
+      end
+
+      def controller_base_path
+        metadata.controller_base_path
+      end
+
+      def camelize_model_properties
+        metadata.camelize_model_properties
+      end
+
+      def resource_path
+        metadata.overridden_resource_path || demod
+      end
+
+      def resource_file_path
+        trim_leading_slash(debased_path.to_s.underscore)
+      end
+
+      def models
+        normalize_model_properties @models
+      end
+
+      def authorizations
+        metadata.authorizations
+      end
+
+      private
+
+      def build_resource_root_hash
+        {
+          "apiVersion" => api_version,
+          "swaggerVersion" => swagger_version,
+          "basePath" => base_path,
+          "resourcePath" => resource_path,
+          "apis" => apis,
+          "resourceFilePath" => resource_file_path,
+          "authorizations"   => authorizations
+        }
+      end
+
+      def normalize_model_properties(models)
+        Hash[
+          models.map do |k, v|
+            if camelize_model_properties
+              [k.to_s, camelize_keys_deep(v)]
+            else
+              [k.to_s, stringify_keys_deep(v)]
+            end
+          end]
+      end
+
+      def demod
+        "#{debased_path.to_s.camelize}".demodulize.camelize.underscore
+      end
+
+      def debased_path
+        path.gsub("#{controller_base_path}", "")
+      end
+
+      def trim_leading_slash(str)
+        return str if !str
+        str.gsub(/\A\/+/, '')
+      end
+
+      def camelize_keys_deep(obj)
+        process_keys_deep(obj){|key| key.to_s.camelize(:lower)}
+      end
+
+      def stringify_keys_deep(obj)
+        process_keys_deep(obj){|key| key.to_s}
+      end
+
+      def process_keys_deep(obj, &block)
+        if obj.is_a? Hash
+          Hash[
+            obj.map do |k, v|
+              new_key =  block.call(k)
+              new_value = process_keys_deep v, &block
+              [new_key, new_value]
+            end
+          ]
+        elsif obj.is_a? Array
+          new_value = obj.collect do |a|
+            process_keys_deep a, &block
+          end
+        else
+          obj
+        end
+      end
+
+    end
+  end
+end

data/lib/swagger/docs/api_declaration_file_metadata.rb

@@ -0,0 +1,22 @@
+module Swagger
+  module Docs
+    class ApiDeclarationFileMetadata
+      DEFAULT_SWAGGER_VERSION = "1.2"
+      DEFAULT_RESOURCE_PATH = nil
+
+      attr_reader :api_version, :path, :base_path, :controller_base_path, :swagger_version, :camelize_model_properties
+      attr_reader :authorizations, :overridden_resource_path
+
+      def initialize(api_version, path, base_path, controller_base_path, options={})
+        @api_version = api_version
+        @path = path
+        @base_path = base_path
+        @controller_base_path = controller_base_path
+        @swagger_version = options.fetch(:swagger_version, DEFAULT_SWAGGER_VERSION)
+        @camelize_model_properties = options.fetch(:camelize_model_properties, true)
+        @authorizations = options.fetch(:authorizations, {})
+        @overridden_resource_path = options.fetch(:resource_path, DEFAULT_RESOURCE_PATH)
+      end
+    end
+  end
+end

data/lib/swagger/docs/config.rb

@@ -0,0 +1,63 @@
+module Swagger
+  module Docs
+    class Config
+      class << self
+        @@base_api_controller = nil
+
+        def base_api_controller
+          @@base_api_controller || ActionController::Base
+        end
+
+        def base_api_controllers
+          Array(base_api_controller)
+        end
+
+        def base_api_controller=(controller)
+          @@base_api_controller = controller
+        end
+
+        alias_method :base_api_controllers=, :base_api_controller=
+
+        def base_applications
+          Array(base_application)
+        end
+
+        def base_application
+          Rails.application
+        end
+
+        def register_apis(versions)
+          base_api_controllers.each do |controller|
+            controller.send(:include, ImpotentMethods)
+          end
+          @versions = versions
+        end
+
+        def registered_apis
+          @versions ||= {}
+        end
+
+        def transform_path(path, api_version)
+          # This is only for overriding, so don't perform any path transformations by default.
+          path
+        end
+
+        def log_exception
+          yield
+          rescue => e
+            write_log(:error, e)
+            raise
+        end
+
+        def log_env_name
+          'SD_LOG_LEVEL'
+        end
+
+        def write_log(type, output)
+          $stderr.puts output if type == :error and ENV[log_env_name]=="1"
+        end
+
+      end
+    end
+  end
+end

data/lib/swagger/docs/dsl.rb

@@ -0,0 +1,119 @@
+module Swagger
+  module Docs
+    class SwaggerDSL
+      # http://stackoverflow.com/questions/5851127/change-the-context-binding-inside-a-block-in-ruby/5851325#5851325
+      def self.call(action, caller, &block)
+        # Create a new SwaggerDSL instance, and instance_eval the block to it
+        instance = new
+        instance.instance_eval(&block)
+        # Now return all of the set instance variables as a Hash
+        instance.instance_variables.inject({}) { |result_hash, instance_variable|
+          result_hash[instance_variable] = instance.instance_variable_get(instance_variable)
+          result_hash # Gotta have the block return the result_hash
+        }
+      end
+
+      def summary(text)
+        @summary = text
+      end
+
+      def notes(text)
+        @notes = text
+      end
+
+      def method(method)
+        @method = method
+      end
+
+      def type(type)
+        @type = type
+      end
+
+      def items(items)
+        @items = items
+      end
+
+      def consumes(mime_types)
+        @consumes = mime_types
+      end
+
+      def nickname(nickname)
+        @nickname = nickname
+      end
+
+      def parameters
+        @parameters ||= []
+      end
+
+      def param(param_type, name, type, required, description = nil, hash={})
+        parameters << {:param_type => param_type, :name => name, :type => type,
+          :description => description, :required => required == :required}.merge(hash)
+      end
+
+      # helper method to generate enums
+      def param_list(param_type, name, type, required, description = nil, allowed_values = [], hash = {})
+        hash.merge!({allowable_values: {value_type: "LIST", values: allowed_values}})
+        param(param_type, name, type, required, description, hash)
+      end
+
+      def response_messages
+        @response_messages ||= []
+      end
+
+      def response(status, text = nil, model = nil)
+        if status.is_a? Symbol
+          status = :ok if status == :success
+          status_code = Rack::Utils.status_code(status)
+          response_messages << {:code => status_code, :responseModel => model, :message => text || status.to_s.titleize}
+        else
+          response_messages << {:code => status, :responseModel => model, :message => text}
+        end
+        response_messages.sort_by!{|i| i[:code]}
+      end
+    end
+
+    class SwaggerModelDSL
+      attr_accessor :id
+
+      # http://stackoverflow.com/questions/5851127/change-the-context-binding-inside-a-block-in-ruby/5851325#5851325
+      def self.call(model_name, caller, &block)
+        # Create a new SwaggerModelDSL instance, and instance_eval the block to it
+        instance = new
+        instance.instance_eval(&block)
+        instance.id = model_name
+        # Now return all of the set instance variables as a Hash
+        instance.instance_variables.inject({}) { |result_hash, instance_var_name|
+          key = instance_var_name[1..-1].to_sym  # Strip prefixed @ sign.
+          result_hash[key] = instance.instance_variable_get(instance_var_name)
+          result_hash # Gotta have the block return the result_hash
+        }
+      end
+
+      def properties
+        @properties ||= {}
+      end
+
+      def required
+        @required ||= []
+      end
+
+      def description(description)
+        @description = description
+      end
+
+      def property(name, type, required, description = nil, hash={})
+        properties[name] = {
+          type: type,
+          description: description,
+        }.merge!(hash)
+        self.required << name if required == :required
+      end
+
+      # helper method to generate enums
+      def property_list(name, type, required, description = nil, allowed_values = [], hash = {})
+        hash.merge!({allowable_values: {value_type: "LIST", values: allowed_values}})
+        property(name, type, required, description, hash)
+      end
+    end
+  end
+end

data/lib/swagger/docs/generator.rb

@@ -0,0 +1,327 @@
+module Swagger
+  module Docs
+    class Generator
+
+      DEFAULT_VER = "1.0"
+      DEFAULT_CONFIG = {
+        :api_file_path => "public/",
+        :api_file_name => "api-docs.json",
+        :base_path => "/",
+        :clean_directory => false,
+        :formatting => :pretty
+      }
+
+      class << self
+
+        def set_real_methods
+          # replace impotent methods with live ones
+          Config.base_api_controllers.each do |controller|
+            controller.send(:include, Methods)
+          end
+        end
+
+        def write_docs(apis = nil)
+          results = generate_docs(apis)
+          results.each{|api_version, result| write_doc(result) }
+        end
+
+        def write_doc(result)
+          settings = result[:settings]
+          config = result[:config]
+          create_output_paths(settings[:api_file_path])
+          clean_output_paths(settings[:api_file_path]) if config[:clean_directory] || false
+          root = result[:root]
+          resources = root.delete 'resources'
+          root.merge!(config[:attributes] || {}) # merge custom user attributes like info
+          # write the api-docs file
+          write_to_file("#{settings[:api_file_path]}/#{config[:api_file_name]}", root, config)
+          # write the individual resource files
+          resources.each do |resource|
+            resource_file_path = resource.delete 'resourceFilePath'
+            write_to_file(File.join(settings[:api_file_path], "#{resource_file_path}.json"), resource, config)
+          end
+          result
+        end
+
+        def generate_docs(apis=nil)
+          apis ||= Config.registered_apis
+          results = {}
+          set_real_methods
+
+          apis[DEFAULT_VER] = DEFAULT_CONFIG if apis.empty?
+
+          apis.each do |api_version, config|
+            settings = get_settings(api_version, config)
+            config.reverse_merge!(DEFAULT_CONFIG)
+            results[api_version] = generate_doc(api_version, settings, config)
+            results[api_version][:settings] = settings
+            results[api_version][:config] = config
+          end
+          results
+        end
+
+        def generate_doc(api_version, settings, config)
+          root = {
+            "swagger" => "2.0",
+            # "info" => settings[:info],
+            "host" => settings[:host],
+            "basePath" => settings[:base_path],
+            "schemes" => [
+                "http"
+            ],
+
+            :paths => {},
+          }
+
+          results = {:processed => [], :skipped => []}
+          resources = []
+
+          get_route_paths(settings[:controller_base_path]).each do |path|
+            ret = process_path(path, root, config, settings)
+            results[ret[:action]] << ret
+
+            if ret[:action] == :processed
+              resources << generate_resource(ret[:path], ret[:apis], ret[:models], settings, root, config, ret[:klass].swagger_config)
+              debased_path = get_debased_path(ret[:path], settings[:controller_base_path])
+
+              ret[:apis] && ret[:apis].each do |rea|
+                name = rea[:path].gsub('.json', '')
+                name += '/' if root[:paths].has_key?(name)
+
+                api_content = rea[:operations][0]
+                description = ret[:klass].swagger_config[:description]
+
+                resource_api = {
+                  # path: "/#{Config.transform_path(trim_leading_slash(debased_path), api_version)}.{format}",
+                  "#{name}" => {
+                    "#{api_content[:method]}" => {
+                      "summary" => api_content[:summary],
+                      "description" => description,
+                      "parameters" => api_content[:parameters].map{|pr| {
+                                        "name" => pr[:name],
+                                        "in" => pr[:param_type],
+                                        "required" => pr[:required] ? true : false,
+                                        "description" => pr[:description],
+                                        "type" => pr[:type]
+                                      }
+                                    },
+                      "responses" => {
+                        "200" => {
+                          "description" => description,
+                          "schema" => {
+                              # "type": "array",
+                              # "items": {
+                              #     "properties": {
+                              #         "firstName": {
+                              #             "type": "string"
+                              #         },
+                              #         "lastName": {
+                              #             "type": "string"
+                              #         },
+                              #         "username": {
+                              #             "type": "string"
+                              #         }
+                              #     }
+                              # }
+                          }
+                        }
+                      }
+                    }
+                  }
+                }.as_json
+                # root[:apis] << resource_api
+                root[:paths].merge!(resource_api)
+              end
+
+            end
+          end
+          root['resources'] = resources
+          results[:root] = root
+          results
+        end
+
+        private
+
+        def transform_spec_to_api_path(spec, controller_base_path, extension)
+          api_path = spec.to_s.dup
+          api_path.gsub!('(.:format)', extension ? ".#{extension}" : '')
+          api_path.gsub!(/:(\w+)/, '{\1}')
+          api_path.gsub!(controller_base_path, '')
+          "/" + trim_slashes(api_path)
+        end
+
+        def camelize_keys_deep!(h)
+          h.keys.each do |k|
+            ks    = k.to_s.camelize(:lower)
+            h[ks] = h.delete k
+            camelize_keys_deep! h[ks] if h[ks].kind_of? Hash
+            if h[ks].kind_of? Array
+              h[ks].each do |a|
+                next unless a.kind_of? Hash
+                camelize_keys_deep! a
+              end
+            end
+          end
+        end
+
+        def trim_leading_slash(str)
+          return str if !str
+          str.gsub(/\A\/+/, '')
+        end
+
+        def trim_trailing_slash(str)
+          return str if !str
+          str.gsub(/\/+\z/, '')
+        end
+
+        def trim_slashes(str)
+          trim_leading_slash(trim_trailing_slash(str))
+        end
+
+        def get_debased_path(path, controller_base_path)
+          path.gsub("#{controller_base_path}", "")
+        end
+
+        def process_path(path, root, config, settings)
+          return {action: :skipped, reason: :empty_path} if path.empty?
+          klass = Config.log_exception { "#{path.to_s.camelize}Controller".constantize } rescue nil
+          return {action: :skipped, path: path, reason: :klass_not_present} if !klass
+          return {action: :skipped, path: path, reason: :not_swagger_resource} if !klass.methods.include?(:swagger_config) or !klass.swagger_config[:controller]
+          return {action: :skipped, path: path, reason: :not_kind_of_parent_controller} if config[:parent_controller] && !(klass < config[:parent_controller])
+          apis, models, defined_nicknames = [], {}, []
+          routes.select{|i| i.defaults[:controller] == path}.each do |route|
+            unless nickname_defined?(defined_nicknames, path, route) # only add once for each route once e.g. PATCH, PUT
+              ret = get_route_path_apis(path, route, klass, settings, config)
+              apis = apis + ret[:apis]
+              models.merge!(ret[:models])
+              defined_nicknames << ret[:nickname] if ret[:nickname].present?
+            end
+          end
+          {action: :processed, path: path, apis: apis, models: models, klass: klass}
+        end
+
+        def route_verbs(route)
+          if defined?(route.verb.source) then route.verb.source.to_s.delete('$'+'^').split('|') else [route.verb] end.collect{|verb| verb.downcase.to_sym}
+        end
+
+        def path_route_nickname(path, route)
+          action = route.defaults[:action]
+          "#{path.camelize}##{action}"
+        end
+
+        def nickname_defined?(defined_nicknames, path, route)
+          target_nickname = path_route_nickname(path, route)
+          defined_nicknames.each{|nickname| return true if nickname == target_nickname }
+          false
+        end
+
+        def generate_resource(path, apis, models, settings, root, config, swagger_config)
+          metadata = ApiDeclarationFileMetadata.new(
+            root["apiVersion"], path, root["basePath"],
+            settings[:controller_base_path],
+            camelize_model_properties: config.fetch(:camelize_model_properties, true),
+            swagger_version: root["swaggerVersion"],
+            authorizations: root[:authorizations],
+            resource_path: swagger_config[:resource_path]
+          )
+          declaration = ApiDeclarationFile.new(metadata, apis, models)
+          declaration.generate_resource
+        end
+
+        def routes
+          Config.base_applications.map{|app| app.routes.routes.to_a }.flatten
+        end
+
+        def get_route_path_apis(path, route, klass, settings, config)
+          models, apis = {}, []
+          action = route.defaults[:action]
+          verbs = route_verbs(route)
+          return {apis: apis, models: models, nickname: nil} if !operation = klass.swagger_actions[action.to_sym]
+          operation = Hash[operation.map {|k, v| [k.to_s.gsub("@","").to_sym, v.respond_to?(:deep_dup) ? v.deep_dup : v.dup] }] # rename :@instance hash keys
+          nickname = operation[:nickname] = path_route_nickname(path, route)
+
+          route_path = if defined?(route.path.spec) then route.path.spec else route.path end
+          api_path = transform_spec_to_api_path(route_path, settings[:controller_base_path], config[:api_extension_type])
+          operation[:parameters] = filter_path_params(api_path, operation[:parameters]) if operation[:parameters]
+          operations = verbs.collect{|verb|
+            op = operation.dup
+            op[:method] = verb
+            op
+          }
+          apis << {:path => api_path, :operations => operations}
+          models = get_klass_models(klass)
+
+          {apis: apis, models: models, nickname: nickname}
+        end
+
+        def get_klass_models(klass)
+          models = {}
+          # Add any declared models to the root of the resource.
+          klass.swagger_models.each do |model_name, model|
+            formatted_model = {
+              id: model[:id],
+              required: model[:required],
+              properties: model[:properties],
+            }
+            formatted_model[:description] = model[:description] if model[:description]
+            models[model[:id]] = formatted_model
+          end
+          models
+        end
+
+        def get_settings(api_version, config)
+          base_path = trim_trailing_slash(config[:base_path] || "")
+          controller_base_path = trim_leading_slash(config[:controller_base_path] || "")
+          base_path += "/#{controller_base_path}" unless controller_base_path.empty?
+          api_file_path = config[:api_file_path]
+          authorizations = config[:authorizations]
+
+          # new version
+          host = config[:host]
+          info = config[:attributes][:info]
+          settings = {
+            base_path: base_path,
+            controller_base_path: controller_base_path,
+            api_file_path: api_file_path,
+            authorizations: authorizations,
+
+            info: info,
+            host: host
+          }.freeze
+        end
+
+        def get_route_paths(controller_base_path)
+          paths = routes.map{|i| "#{i.defaults[:controller]}" }
+          paths.uniq.select{|i| i.start_with?(controller_base_path)}
+        end
+
+        def create_output_paths(api_file_path)
+          FileUtils.mkdir_p(api_file_path) # recursively create out output path
+        end
+
+        def clean_output_paths(api_file_path)
+          Dir.foreach(api_file_path) do |f|
+            fn = File.join(api_file_path, f)
+            File.delete(fn) if !File.directory?(fn) and File.extname(fn) == '.json'
+          end
+        end
+
+        def write_to_file(path, structure, config={})
+          content = case config[:formatting]
+            when :pretty; JSON.pretty_generate structure
+            else;         structure.to_json
+          end
+          FileUtils.mkdir_p File.dirname(path)
+          File.open(path, 'w') { |file| file.write content }
+        end
+
+        def filter_path_params(path, params)
+          params.reject do |param|
+            param_as_variable = "{#{param[:name]}}"
+            param[:param_type] == :path && !path.include?(param_as_variable)
+          end
+        end
+      end
+    end
+  end
+end