swagger-docs 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f824965e424cbfdcd8551dea96dbabe88e7368fd
-  data.tar.gz: 2a02f6c05ea8aa87659b022f4807bf2a9874639f
+  metadata.gz: 9940ad082299dc2d0d6cb34a3e7c1336a37e0c8b
+  data.tar.gz: 9f75192abe6f35735aea5b4948482211177b5cf0
 SHA512:
-  metadata.gz: 81971dd258cb50fae6a2a0e8c6837deff20da9f9067e6a4a433b6c04e4a3351fa035d59871fb263f96bae53db2164b9b053013d487e427129619ad3956c7b8bd
-  data.tar.gz: 817550eddc45f754818bebdfa134fc6bff885a6fa6796116bf2f7da4530bba0458f2cc076e569d16dc602129177c14f7969bb8ca3b7a33eb9f0f8a4a80a950e5
+  metadata.gz: 9d1a4e4f8a4c83ed76b547414ff6c1ac1887d3570bcb43b90b665d7e8ca9c97ee7f5de6cdd097d5c790bac0a8fdf2dbd53b04c72ae892e85c415b0757bdd444b
+  data.tar.gz: abba4ab15746a0ec3e1b8c8b2bbe78f35c62438289ed53641b1b682c5204eb971f7b6c67d67103a29093c5eb5eb49025a6194012b6564f07cdc4229c0e44b875

data/CHANGELOG.md

@@ -1,3 +1,13 @@
+## 0.1.2
+- Add suport for Swagger models
+- Use ActionControlller::Base instead of ApplicationController. fixes #27
+- Status codes for response
+- Path generation fixes #26 @stevschmid
+- Ignore path filtering when no params are set
+- Add param_list helper for generating enums/lists
+- Improve structure of generator class - break up large methods
+- Fix the destination path of the resource files #30
+
 ## 0.1.1
 - Add support for Rails engines (@fotinakis)
 - Filter out path parameters if the parameter is not in the path (@stevschmid)

data/README.md

@@ -42,11 +42,11 @@ Swagger::Docs::Config.register_apis({
     # the extension used for the API
     :api_extension_type => :json,
     # the output location where your .json files are written to
-    :api_file_path => "public/api/v1/", 
-    # the URL base path to your API 
-    :base_path => "http://api.somedomain.com", 
+    :api_file_path => "public/api/v1/",
+    # the URL base path to your API
+    :base_path => "http://api.somedomain.com",
     # if you want to delete all .json files at each generation
-    :clean_directory => false 
+    :clean_directory => false
   }
 })
 ```
@@ -109,8 +109,9 @@ class Api::V1::UsersController < ApplicationController
   swagger_api :index do
     summary "Fetches all User items"
     param :query, :page, :integer, :optional, "Page number"
+    param :path, :nested_id, :integer, :optional, "Team Id"
     response :unauthorized
-    response :not_acceptable
+    response :not_acceptable, "The request you made is not acceptable"
     response :requested_range_not_satisfiable
   end
 
@@ -127,6 +128,7 @@ class Api::V1::UsersController < ApplicationController
     param :form, :first_name, :string, :required, "First name"
     param :form, :last_name, :string, :required, "Last name"
     param :form, :email, :string, :required, "Email address"
+    param_list :form, :role, :string, :required, "Role", [ "admin", "superadmin", "user" ]
     response :unauthorized
     response :not_acceptable
   end
@@ -137,6 +139,7 @@ class Api::V1::UsersController < ApplicationController
     param :form, :first_name, :string, :optional, "First name"
     param :form, :last_name, :string, :optional, "Last name"
     param :form, :email, :string, :optional, "Email address"
+    param :form, :tag, :Tag, :required, "Tag object"
     response :unauthorized
     response :not_found
     response :not_acceptable
@@ -149,9 +152,51 @@ class Api::V1::UsersController < ApplicationController
     response :not_found
   end
 
+  # Support for Swagger complex types:
+  # https://github.com/wordnik/swagger-core/wiki/Datatypes#wiki-complex-types
+  swagger_model :Tag do
+    description "A Tag object."
+    property :id, :integer, :required, "User Id"
+    property :name, :string, :optional, "Name"
+  end
+
 end
 ```
 
+### DSL Methods
+
+<table>
+<thead>
+<tr>
+<th>Method</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+
+<tr>
+<td>summary</td>
+<td>The summary of the API</td>
+</tr>
+
+<tr>
+<td>param</td>
+<td>Standard API Parameter</td>
+</tr>
+
+<tr>
+<td>param_list</td>
+<td>Standard API Enum/List parameter.</td>
+</tr>
+
+<tr>
+<td>response</td>
+<td>Takes a symbol or status code and passes it to `Rack::Utils.status_code`. The current list of status codes can be seen here: https://github.com/rack/rack/blob/master/lib/rack/utils.rb. An optional message can be added.</td>
+</tr>
+
+</tbody>
+</table>
+
 ### Run rake task to generate docs
 
 ```
@@ -160,7 +205,7 @@ rake swagger:docs
 
 Swagger-ui JSON files should now be present in your api_file_path (e.g. ./public/api/v1)
 
-### Sample 
+### Sample
 
 A sample Rails application where you can run the above rake command and view the output in swagger-ui can be found here:
 
@@ -173,8 +218,8 @@ https://github.com/richhollis/swagger-docs-sample
 
 #### Inheriting from a custom Api controller
 
-By default swagger-docs is applied to controllers inheriting from ApplicationController. 
-If this is not the case for your application, use this snippet in your initializer 
+By default swagger-docs is applied to controllers inheriting from ApplicationController.
+If this is not the case for your application, use this snippet in your initializer
 _before_ calling Swagger::Docs::Config#register_apis(...).
 
 ```ruby
@@ -194,7 +239,6 @@ class Swagger::Docs::Config
 end
 ```
 
-=======
 #### Transforming the `path` variable
 
 Swagger allows a distinction between the API documentation server and the hosted API
@@ -253,7 +297,7 @@ users.json output:
 {
   "apiVersion": "1.0",
   "swaggerVersion": "1.2",
-  "basePath": "/api/v1",
+  "basePath": "http://api.somedomain.com/api/v1/",
   "resourcePath": "/users",
   "apis": [
     {
@@ -277,7 +321,47 @@ users.json output:
             },
             {
               "code": 406,
-              "message": "Not Acceptable"
+              "message": "The request you made is not acceptable"
+            },
+            {
+              "code": 416,
+              "message": "Requested Range Not Satisfiable"
+            }
+          ],
+          "method": "get",
+          "nickname": "Api::V1::Users#index"
+        }
+      ]
+    },
+    {
+      "path": "nested/{nested_id}/sample",
+      "operations": [
+        {
+          "summary": "Fetches all User items",
+          "parameters": [
+            {
+              "paramType": "query",
+              "name": "page",
+              "type": "integer",
+              "description": "Page number",
+              "required": false
+            },
+            {
+              "paramType": "path",
+              "name": "nested_id",
+              "type": "integer",
+              "description": "Team Id",
+              "required": false
+            }
+          ],
+          "responseMessages": [
+            {
+              "code": 401,
+              "message": "Unauthorized"
+            },
+            {
+              "code": 406,
+              "message": "The request you made is not acceptable"
             },
             {
               "code": 416,
@@ -398,6 +482,13 @@ users.json output:
               "type": "string",
               "description": "Email address",
               "required": false
+            },
+            {
+              "paramType": "form",
+              "name": "tag",
+              "type": "Tag",
+              "description": "Tag object",
+              "required": true
             }
           ],
           "responseMessages": [
@@ -448,7 +539,27 @@ users.json output:
         }
       ]
     }
-  ]
+  ],
+  "models": {
+    "Tag": {
+      "id": "Tag",
+      "required": [
+        "id"
+      ],
+      "properties": {
+        "id": {
+          "type": "integer",
+          "description": "User Id"
+        },
+        "name": {
+          "type": "string",
+          "description": "Name",
+          "foo": "test"
+        }
+      },
+      "description": "A Tag object."
+    }
+  }
 }
 ```
 

data/lib/swagger/docs/config.rb

@@ -2,7 +2,7 @@ module Swagger
   module Docs
     class Config
       class << self
-        def base_api_controller; ApplicationController end
+        def base_api_controller; ActionController::Base end
         def base_application; Rails.application end
         def register_apis(versions)
           base_api_controller.send(:include, ImpotentMethods)

data/lib/swagger/docs/dsl.rb

@@ -2,10 +2,10 @@ 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, &blk)
-        # Create a new CommandDSL instance, and instance_eval the block to it
+      def self.call(action, caller, &block)
+        # Create a new SwaggerDSL instance, and instance_eval the block to it
         instance = new
-        instance.instance_eval(&blk)
+        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)
@@ -38,6 +38,12 @@ module Swagger
           :description => description, :required => required == :required ? true : false}.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 = nil, hash)
+      end
+
       def response_messages
         @response_messages ||= []
       end
@@ -52,5 +58,43 @@ module Swagger
         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 ? true : false)
+      end
+    end
   end
 end

data/lib/swagger/docs/generator.rb

@@ -12,6 +12,63 @@ module Swagger
 
       class << self
 
+        def set_real_methods
+          Config.base_api_controller.send(:include, Methods) # replace impotent methods with live ones
+        end
+
+        def write_docs(apis = nil)
+          apis ||= Config.registered_apis
+          results = {}
+          set_real_methods
+          unless apis.empty?
+            apis.each do |api_version,config|
+              config.reverse_merge!(DEFAULT_CONFIG)
+              results[api_version] = write_doc(api_version, config)
+            end
+          else
+            results[DEFAULT_VER] = write_doc(DEFAULT_VER, DEFAULT_CONFIG)
+          end
+          results
+        end
+
+        def write_doc(api_version, config)
+          settings = get_settings(api_version, config)
+
+          create_output_paths(settings[:api_file_path])
+          clean_output_paths(settings[:api_file_path]) if config[:clean_directory] || false
+
+          root = { :api_version => api_version, :swagger_version => "1.2", :base_path => settings[:base_path] + "/", :apis => []}
+          results = {:processed => [], :skipped => []}
+
+          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
+              create_resource_file(ret[:path], ret[:apis], ret[:models], settings, root, config)
+              debased_path = get_debased_path(ret[:path], settings[:controller_base_path])
+              resource_api = {
+                path: "#{Config.transform_path(trim_leading_slash(debased_path))}.{format}",
+                description: ret[:klass].swagger_config[:description]
+              }
+              root[:apis] << resource_api
+            end
+          end
+
+          camelize_keys_deep!(root)
+          write_to_file("#{settings[:api_file_path]}/api-docs.json", root, config)
+          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)
@@ -26,107 +83,108 @@ module Swagger
           end
         end
 
-        def get_api_path(spec, extension)
-          extension = ".#{extension}" if extension
-          path_api = trim_leading_slash(spec.to_s.gsub("(.:format)", extension.to_s))
-          parts_new = []
-          path_api.split("/").each do |path_part|
-            part = path_part
-            if part[0] == ":"
-              part[0] = "{"
-              part << "}"
-            end
-            parts_new << part
-          end
-          path_api = parts_new*"/"
-        end
-
         def trim_leading_slash(str)
           return str if !str
-          return str unless str[0] == '/'
-          str[1..-1]
+          str.gsub(/\A\/+/, '')
         end
 
         def trim_trailing_slash(str)
           return str if !str
-          return str unless str[-1] == '/'
-          str[0..-2]
+          str.gsub(/\/+\z/, '')
         end
 
         def trim_slashes(str)
           trim_leading_slash(trim_trailing_slash(str))
         end
 
-        def set_real_methods
-          Config.base_api_controller.send(:include, Methods) # replace impotent methods with live ones
+        def get_debased_path(path, controller_base_path)
+          path.gsub("#{controller_base_path}", "")
         end
 
-        def write_docs(apis = nil)
-          apis ||= Config.registered_apis
-          results = {}
-          set_real_methods
-          unless apis.empty?
-            apis.each do |api_version,config|
-              config.reverse_merge!(DEFAULT_CONFIG)
-              results[api_version] = write_doc(api_version, config)
-            end
-          else
-            results[DEFAULT_VER] = write_doc(DEFAULT_VER, DEFAULT_CONFIG)
+        def process_path(path, root, config, settings)
+          return {action: empty} if path.empty?
+          klass = "#{path.to_s.camelize}Controller".constantize
+          return {action: :skipped, path: path} if !klass.methods.include?(:swagger_config) or !klass.swagger_config[:controller]
+          apis, models = [], {}
+          Config.base_application.routes.routes.select{|i| i.defaults[:controller] == path}.each do |route|
+            ret = get_route_path_apis(path, route, klass, settings, config)
+            apis = apis + ret[:apis]
+            models.merge!(ret[:models])
           end
-          results
+          {action: :processed, path: path, apis: apis, models: models, klass: klass}
         end
 
-        def write_doc(api_version, config)
-          base_path = trim_trailing_slash(config[:base_path] || "")
-          controller_base_path = trim_leading_slash(config[:controller_base_path] || "")
-          api_file_path = config[:api_file_path]
-          clean_directory = config[:clean_directory] || false
-          results = {:processed => [], :skipped => []}
+        def create_resource_file(path, apis, models, settings, root, config)
+          debased_path = get_debased_path(path, settings[:controller_base_path])
+          demod = "#{debased_path.to_s.camelize}".demodulize.camelize.underscore
+          resource_path = trim_leading_slash(debased_path.to_s.underscore)
+          resource = root.merge({:resource_path => "#{demod}", :apis => apis})
+          camelize_keys_deep!(resource)
+          # Add the already-normalized models to the resource.
+          resource = resource.merge({:models => models}) if models.present?
+          # write controller resource file
+          write_to_file(File.join(settings[:api_file_path], "#{resource_path}.json"), resource, config)
+        end
 
-          # create output paths
-          FileUtils.mkdir_p(api_file_path) # recursively create out output path
-          Dir.foreach(api_file_path) {|f| fn = File.join(api_file_path, f); File.delete(fn) if !File.directory?(fn) and File.extname(fn) == '.json'} if clean_directory # clean output path
+        def get_route_path_apis(path, route, klass, settings, config)
+          models, apis = {}, []
+          action = route.defaults[:action]
+          verb = route.verb.source.to_s.delete('$'+'^').downcase.to_sym
+          return apis if !operations = klass.swagger_actions[action.to_sym]
+          operations = Hash[operations.map {|k, v| [k.to_s.gsub("@","").to_sym, v.respond_to?(:deep_dup) ? v.deep_dup : v.dup] }] # rename :@instance hash keys
+          operations[:method] = verb
+          operations[:nickname] = "#{path.camelize}##{action}"
+          
+          api_path = transform_spec_to_api_path(route.path.spec, settings[:controller_base_path], config[:api_extension_type])
+          operations[:parameters] = filter_path_params(api_path, operations[:parameters]) if operations[:parameters]
+
+          apis << {:path => api_path, :operations => [operations]}
+          models = get_klass_models(klass)          
+
+          {apis: apis, models: models}
+        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?
-          header = { :api_version => api_version, :swagger_version => "1.2", :base_path => base_path + "/"}
-          resources = header.merge({:apis => []})
+          api_file_path = config[:api_file_path]          
+          settings = { 
+            base_path: base_path,
+            controller_base_path: controller_base_path,
+            api_file_path: api_file_path
+          }.freeze
+        end
 
+        def get_route_paths(controller_base_path)
           paths = Config.base_application.routes.routes.map{|i| "#{i.defaults[:controller]}" }
-          paths = paths.uniq.select{|i| i.start_with?(controller_base_path)}
-          paths.each do |path|
-            next if path.empty?
-            klass = "#{path.to_s.camelize}Controller".constantize
-            if !klass.methods.include?(:swagger_config) or !klass.swagger_config[:controller]
-              results[:skipped] << path
-              next
-            end
-            apis = []
-            debased_path = path.gsub("#{controller_base_path}", "")
-            Config.base_application.routes.routes.select{|i| i.defaults[:controller] == path}.each do |route|
-              action = route.defaults[:action]
-              verb = route.verb.source.to_s.delete('$'+'^').downcase.to_sym
-              next if !operations = klass.swagger_actions[action.to_sym]
-              operations = Hash[operations.map {|k, v| [k.to_s.gsub("@","").to_sym, v.respond_to?(:deep_dup) ? v.deep_dup : v.dup] }] # rename :@instance hash keys
-              operations[:method] = verb
-              operations[:nickname] = "#{path.camelize}##{action}"
-              api_path = trim_slashes(get_api_path(trim_leading_slash(route.path.spec.to_s), config[:api_extension_type]).gsub("#{controller_base_path}",""))
-              operations[:parameters] = filter_path_params(api_path, operations[:parameters])
-              apis << {:path => api_path, :operations => [operations]}
-            end
-            demod = "#{debased_path.to_s.camelize}".demodulize.camelize.underscore
-            resource = header.merge({:resource_path => "#{demod}", :apis => apis})
-            camelize_keys_deep!(resource)
-            # write controller resource file
-            write_to_file "#{api_file_path}/#{demod}.json", resource, config
-            # append resource to resources array (for writing out at end)
-            resources[:apis] << {path: "#{Config.transform_path(trim_leading_slash(debased_path))}.{format}", description: klass.swagger_config[:description]}
-            results[:processed] << path
-          end
-          # write master resource file
-          camelize_keys_deep!(resources)
+          paths.uniq.select{|i| i.start_with?(controller_base_path)}
+        end
 
-          write_to_file "#{api_file_path}/api-docs.json", resources, config
-          results
+        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={})
@@ -134,11 +192,10 @@ module Swagger
             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
 
-        private
-
         def filter_path_params(path, params)
           params.reject do |param|
             param_as_variable = "{#{param[:name]}}"

data/lib/swagger/docs/impotent_methods.rb

@@ -12,6 +12,9 @@ module Swagger
         def swagger_api(action, &block)
         end
 
+        def swagger_model(model_name, &block)
+        end
+
         def swagger_controller(controller, description)
         end
       end

data/lib/swagger/docs/methods.rb

@@ -11,14 +11,14 @@ module Swagger
           swagger_config[:description] = description
         end
 
-        def swagger_model(model)
-          swagger_config[:model] = model
-        end
-
         def swagger_actions
           @swagger_dsl
         end
 
+        def swagger_models
+          @swagger_model_dsls ||= {}
+        end
+
         def swagger_config
           @swagger_config ||= {}
         end
@@ -27,12 +27,16 @@ module Swagger
 
         def swagger_api(action, &block)
           @swagger_dsl ||= {}
-          controller_action = "#{name}##{action} #{self.class}"
           return if @swagger_dsl[action]
-          route = Swagger::Docs::Config.base_application.routes.routes.select{|i| "#{i.defaults[:controller].to_s.camelize}Controller##{i.defaults[:action]}" == controller_action }.first
           dsl = SwaggerDSL.call(action, self, &block)
           @swagger_dsl[action] = dsl
         end
+
+        def swagger_model(model_name, &block)
+          @swagger_model_dsls ||= {}
+          model_dsl = SwaggerModelDSL.call(model_name, self, &block)
+          @swagger_model_dsls[model_name] = model_dsl
+        end
       end
     end
   end

data/lib/swagger/docs/version.rb

@@ -1,5 +1,5 @@
 module Swagger
   module Docs
-    VERSION = "0.1.1"
+    VERSION = "0.1.2"
   end
 end

data/spec/fixtures/controllers/sample_controller.rb

@@ -27,6 +27,7 @@ module Api
         param :form, :first_name, :string, :required, "First name"
         param :form, :last_name, :string, :required, "Last name"
         param :form, :email, :string, :required, "Email address"
+        param_list :form, :role, :string, :required, "Role", [ "admin", "superadmin", "user" ]
         response :unauthorized
         response :not_acceptable
       end
@@ -37,6 +38,7 @@ module Api
         param :form, :first_name, :string, :optional, "First name"
         param :form, :last_name, :string, :optional, "Last name"
         param :form, :email, :string, :optional, "Email address"
+        param :form, :tag, :Tag, :required, "Tag object"
         response :unauthorized
         response :not_found
         response :not_acceptable
@@ -49,6 +51,18 @@ module Api
         response :not_found
       end
 
+      # a method that intentionally has no parameters
+      swagger_api :new do
+        summary "Builds a new User item"
+      end
+
+      # Support for Swagger complex types:
+      # https://github.com/wordnik/swagger-core/wiki/Datatypes#wiki-complex-types
+      swagger_model :Tag do
+        description "A Tag object."
+        property :id, :integer, :required, "User Id"
+        property :name, :string, :optional, "Name", foo: "test"
+      end
     end
   end
 end

data/spec/lib/swagger/docs/generator_spec.rb

@@ -5,19 +5,9 @@ describe Swagger::Docs::Generator do
   require "fixtures/controllers/application_controller"
   require "fixtures/controllers/ignored_controller"
 
-  def generate(config)
-    Swagger::Docs::Generator::write_docs(config)
-  end
-
-  def stub_route(verb, action, controller, spec)
-    double("route", :verb => double("verb", :source => verb),
-                  :defaults => {:action => action, :controller => controller},
-                  :path => double("path", :spec => spec)
-    )
-  end
-
   before(:each) do
-    FileUtils.rm_rf(TMP_DIR)
+    FileUtils.rm_rf(tmp_dir)
+    stub_const('ActionController::Base', ApplicationController)
   end
 
   let(:routes) {[
@@ -27,13 +17,18 @@ describe Swagger::Docs::Generator do
     stub_route("^POST$", "create", "api/v1/sample", "/api/v1/sample(.:format)"),
     stub_route("^GET$", "show", "api/v1/sample", "/api/v1/sample/:id(.:format)"),
     stub_route("^PUT$", "update", "api/v1/sample", "/api/v1/sample/:id(.:format)"),
-    stub_route("^DELETE$", "destroy", "api/v1/sample", "/api/v1/sample/:id(.:format)")
+    stub_route("^DELETE$", "destroy", "api/v1/sample", "/api/v1/sample/:id(.:format)"),
+    stub_route("^GET$", "new", "api/v1/sample", "/api/v1/sample/new(.:format)") # no parameters for this method
   ]}
 
+  let(:tmp_dir) { Pathname.new('/tmp/swagger-docs/') }
+  let(:file_resources) { tmp_dir + 'api-docs.json' }
+  let(:file_resource) { tmp_dir + 'api/v1/sample.json' }
+
   context "without controller base path" do
-    let(:config) { 
+    let(:config) {
       {
-        DEFAULT_VER => {:api_file_path => "#{TMP_DIR}api/v1/", :base_path => "http://api.no.where"}
+        DEFAULT_VER => {:api_file_path => "#{tmp_dir}", :base_path => "http://api.no.where"}
       }
     }
     before(:each) do
@@ -43,7 +38,7 @@ describe Swagger::Docs::Generator do
       generate(config)
     end
     context "resources files" do
-      let(:resources) { FILE_RESOURCES.read }
+      let(:resources) { file_resources.read }
       let(:response) { JSON.parse(resources) }
       it "writes basePath correctly" do
         expect(response["basePath"]).to eq "http://api.no.where/"
@@ -56,7 +51,7 @@ describe Swagger::Docs::Generator do
       end
     end
     context "resource file" do
-      let(:resource) { FILE_RESOURCE.read }
+      let(:resource) { file_resource.read }
       let(:response) { JSON.parse(resource) }
       let(:first) { response["apis"].first }
       let(:operations) { first["operations"] }
@@ -68,7 +63,7 @@ describe Swagger::Docs::Generator do
         expect(response["resourcePath"]).to eq "sample"
       end
       it "writes out expected api count" do
-        expect(response["apis"].count).to eq 6
+        expect(response["apis"].count).to eq 7
       end
       context "first api" do
         #"apis":[{"path":" /sample","operations":[{"summary":"Fetches all User items"
@@ -82,9 +77,10 @@ describe Swagger::Docs::Generator do
 
   context "with controller base path" do
     let(:config) { Swagger::Docs::Config.register_apis({
-      DEFAULT_VER => {:controller_base_path => "api/v1", :api_file_path => "#{TMP_DIR}api/v1/", :base_path => "http://api.no.where"}
+       DEFAULT_VER => {:controller_base_path => "api/v1", :api_file_path => "#{tmp_dir}", :base_path => "http://api.no.where"}
     })}
-    before(:each) do 
+    let(:file_resource) { tmp_dir + 'sample.json' }
+    before(:each) do
       Rails.stub_chain(:application, :routes, :routes).and_return(routes)
       Swagger::Docs::Generator.set_real_methods
       require "fixtures/controllers/sample_controller"
@@ -92,16 +88,16 @@ describe Swagger::Docs::Generator do
 
     context "test suite initialization" do
       it "the resources file does not exist" do
-        expect(FILE_RESOURCES).to_not exist
+        expect(file_resource).to_not exist
       end
       it "the resource file does not exist" do
-        expect(FILE_RESOURCE).to_not exist
+        expect(file_resource).to_not exist
       end
     end
 
     describe "#write_docs" do
       context "no apis registered" do
-        before(:each) do 
+        before(:each) do
           Swagger::Docs::Config.register_apis({})
         end
         it "generates using default config" do
@@ -113,7 +109,7 @@ describe Swagger::Docs::Generator do
         generate(config)
       end
       it "cleans json files in directory when set" do
-        file_to_delete = TMP_DIR+"api/v1/delete_me.json"
+        file_to_delete = Pathname.new(File.join(config['1.0'][:api_file_path], 'delete_me.json'))
         File.open(file_to_delete, 'w') {|f| f.write("{}") }
         expect(file_to_delete).to exist
         config[DEFAULT_VER][:clean_directory] = true
@@ -121,17 +117,17 @@ describe Swagger::Docs::Generator do
         expect(file_to_delete).to_not exist
       end
       it "keeps non json files in directory when cleaning" do
-        file_to_keep = TMP_DIR+"api/v1/keep_me"
+        file_to_keep = Pathname.new(File.join(config['1.0'][:api_file_path], 'keep_me'))
         File.open(file_to_keep, 'w') {|f| f.write("{}") }
         config[DEFAULT_VER][:clean_directory] = true
         generate(config)
         expect(file_to_keep).to exist
       end
       it "writes the resources file" do
-        expect(FILE_RESOURCES).to exist
+         expect(file_resources).to exist
       end
       it "writes the resource file" do
-        expect(FILE_RESOURCE).to exist
+         expect(file_resource).to exist
       end
       it "returns results hash" do
         results = generate(config)
@@ -141,11 +137,11 @@ describe Swagger::Docs::Generator do
       it "writes pretty json files when set" do
         config[DEFAULT_VER][:formatting] = :pretty
         generate(config)
-        resources = File.read FILE_RESOURCES
+        resources = File.read file_resources
         expect(resources.scan(/\n/).length).to be > 1
       end
       context "resources files" do
-        let(:resources) { FILE_RESOURCES.read }
+        let(:resources) { file_resources.read }
         let(:response) { JSON.parse(resources) }
         it "writes version correctly" do
           expect(response["apiVersion"]).to eq DEFAULT_VER
@@ -167,11 +163,9 @@ describe Swagger::Docs::Generator do
         end
       end
       context "resource file" do
-        let(:resource) { FILE_RESOURCE.read }
+        let(:resource) { file_resource.read }
         let(:response) { JSON.parse(resource) }
-        let(:operations) { api["operations"] }
-        let(:params) { operations.first["parameters"] }
-        let(:response_msgs) { operations.first["responseMessages"] }
+        let(:apis) { response["apis"] }
         # {"apiVersion":"1.0","swaggerVersion":"1.2","basePath":"/api/v1","resourcePath":"/sample"
         it "writes version correctly" do
           expect(response["apiVersion"]).to eq DEFAULT_VER
@@ -186,75 +180,124 @@ describe Swagger::Docs::Generator do
           expect(response["resourcePath"]).to eq "sample"
         end
         it "writes out expected api count" do
-          expect(response["apis"].count).to eq 6
+          expect(response["apis"].count).to eq 7
         end
-        context "first api" do
-          let(:api) { response["apis"][0] }
-          #"apis":[{"path":" /sample","operations":[{"summary":"Fetches all User items"
-          #,"method":"get","nickname":"Api::V1::Sample#index"}]
-          it "writes path correctly when api extension type is not set" do
-            expect(api["path"]).to eq "sample"
-          end
-          it "writes path correctly when api extension type is set" do
-            config[DEFAULT_VER][:api_extension_type] = :json
-            generate(config)
-            expect(api["path"]).to eq "sample.json"
-          end
-          it "writes summary correctly" do
-            expect(operations.first["summary"]).to eq "Fetches all User items"
-          end
-          it "writes method correctly" do
-            expect(operations.first["method"]).to eq "get"
-          end
-          it "writes nickname correctly" do
-            expect(operations.first["nickname"]).to eq "Api::V1::Sample#index"
-          end
-          #"parameters"=>[
-          # {"paramType"=>"query", "name"=>"page", "type"=>"integer", "description"=>"Page number", "required"=>false},
-          # {"paramType"=>"path", "name"=>"nested_id", "type"=>"integer", "description"=>"Team Id", "required"=>false}], "responseMessages"=>[{"code"=>401, "message"=>"Unauthorized"}, {"code"=>406, "message"=>"The request you made is not acceptable"}, {"code"=>416, "message"=>"Requested Range Not Satisfiable"}], "method"=>"get", "nickname"=>"Api::V1::Sample#index"}
-          #]
-          context "parameters" do
-            it "has correct count" do
-              expect(params.count).to eq 1
+        context "apis" do
+          context "index" do
+            let(:api) { get_api_operation(apis, "sample", :get) }
+            let(:operations) { get_api_operations(apis, "sample") }
+            #"apis":[{"path":" /sample","operations":[{"summary":"Fetches all User items"
+            #,"method":"get","nickname":"Api::V1::Sample#index"}]
+            it "writes path correctly when api extension type is not set" do
+              expect(apis.first["path"]).to eq "sample"
             end
-            it "writes paramType correctly" do
-              expect(params.first["paramType"]).to eq "query"
+            it "writes path correctly when api extension type is set" do
+              config[DEFAULT_VER][:api_extension_type] = :json
+              generate(config)
+              expect(apis.first["path"]).to eq "sample.json"
             end
-            it "writes name correctly" do
-              expect(params.first["name"]).to eq "page"
+            it "writes summary correctly" do
+              expect(operations.first["summary"]).to eq "Fetches all User items"
             end
-            it "writes type correctly" do
-              expect(params.first["type"]).to eq "integer"
+            it "writes method correctly" do
+              expect(operations.first["method"]).to eq "get"
             end
-            it "writes description correctly" do
-              expect(params.first["description"]).to eq "Page number"
+            it "writes nickname correctly" do
+              expect(operations.first["nickname"]).to eq "Api::V1::Sample#index"
             end
-            it "writes required correctly" do
-              expect(params.first["required"]).to be_false
+            #"parameters"=>[
+            # {"paramType"=>"query", "name"=>"page", "type"=>"integer", "description"=>"Page number", "required"=>false},
+            # {"paramType"=>"path", "name"=>"nested_id", "type"=>"integer", "description"=>"Team Id", "required"=>false}], "responseMessages"=>[{"code"=>401, "message"=>"Unauthorized"}, {"code"=>406, "message"=>"The request you made is not acceptable"}, {"code"=>416, "message"=>"Requested Range Not Satisfiable"}], "method"=>"get", "nickname"=>"Api::V1::Sample#index"}
+            #]
+            context "parameters" do
+              let(:params) { operations.first["parameters"] }
+              it "has correct count" do
+                expect(params.count).to eq 1
+              end
+              it "writes paramType correctly" do
+                expect(params.first["paramType"]).to eq "query"
+              end
+              it "writes name correctly" do
+                expect(params.first["name"]).to eq "page"
+              end
+              it "writes type correctly" do
+                expect(params.first["type"]).to eq "integer"
+              end
+              it "writes description correctly" do
+                expect(params.first["description"]).to eq "Page number"
+              end
+              it "writes required correctly" do
+                expect(params.first["required"]).to be_false
+              end
             end
-          end
-          #"responseMessages":[{"code":401,"message":"Unauthorized"},{"code":406,"message":"Not Acceptable"},{"code":416,"message":"Requested Range Not Satisfiable"}]
-          context "response messages" do
-            it "has correct count" do
-              expect(response_msgs.count).to eq 3
+            #"responseMessages":[{"code":401,"message":"Unauthorized"},{"code":406,"message":"Not Acceptable"},{"code":416,"message":"Requested Range Not Satisfiable"}]
+            context "response messages" do
+              let(:response_msgs) { operations.first["responseMessages"] }
+              it "has correct count" do
+                expect(response_msgs.count).to eq 3
+              end
+              it "writes code correctly" do
+                expect(response_msgs.first["code"]).to eq 401
+              end
+              it "writes message correctly" do
+                expect(response_msgs.first["message"]).to eq "Unauthorized"
+              end
+              it "writes specified message correctly" do
+                expect(response_msgs[1]["message"]).to eq "The request you made is not acceptable"
+              end
             end
-            it "writes code correctly" do
-              expect(response_msgs.first["code"]).to eq 401
+          end
+          context "show" do
+            let(:api) { get_api_operation(apis, "nested/{nested_id}/sample", :get) }
+            let(:operations) { get_api_operations(apis, "nested/{nested_id}/sample") }
+            context "parameters" do
+              it "has correct count" do
+                expect(api["parameters"].count).to eq 2
+              end
             end
-            it "writes message correctly" do
-              expect(response_msgs.first["message"]).to eq "Unauthorized"
+          end
+          context "create" do
+            let(:api) { get_api_operation(apis, "sample", :post) }
+            it "writes list parameter values correctly" do
+              expected_param = {"valueType"=>"LIST", "values"=>["admin", "superadmin", "user"]}
+              expect(get_api_parameter(api, "role")["allowableValues"]).to eq expected_param
             end
-            it "writes specified message correctly" do
-              expect(response_msgs[1]["message"]).to eq "The request you made is not acceptable"
+          end
+          context "update" do
+            let(:api) { get_api_operation(apis, "sample/{id}", :put) }
+            it "writes model param correctly" do
+              expected_param = {
+                "paramType" => "form",
+                "name" => "tag",
+                "type" => "Tag",
+                "description" => "Tag object",
+                "required" => true,
+              }
+              expect(get_api_parameter(api, "tag")).to eq expected_param
             end
           end
         end
-        context "second api (nested)" do
-          let(:api) { response["apis"][1] }
-          context "parameters" do
-            it "has correct count" do
-              expect(params.count).to eq 2
-            end
+        context "models" do
+          let(:models) { response["models"] }
+          # Based on https://github.com/wordnik/swagger-core/wiki/Datatypes
+          it "writes model correctly" do
+            expected_model = {
+              "id" => "Tag",
+              "required" => ["id"],
+              "description" => "A Tag object.",
+              "properties" => {
+                "name" => {
+                  "type" => "string",
+                  "description" => "Name",
+                  "foo" => "test",
+                },
+                "id" => {
+                  "type" => "integer",
+                  "description" => "User Id",
+                }
+              }
+            }
+            expect(models['Tag']).to eq expected_model
           end
         end
       end

data/spec/spec_helper.rb

@@ -6,14 +6,39 @@ require 'pathname'
 
 DEFAULT_VER = Swagger::Docs::Generator::DEFAULT_VER
 
-TMP_DIR = Pathname.new "/tmp/swagger-docs/"
-TMP_API_DIR = TMP_DIR+"api/v1"
-FILE_RESOURCES = TMP_API_DIR+"api-docs.json"
-FILE_RESOURCE = TMP_API_DIR+"sample.json"
-
 RSpec.configure do |config|
   config.expect_with :rspec do |c|
     c.syntax = :expect
   end
   config.color_enabled = true
 end
+
+def generate(config)
+    Swagger::Docs::Generator::write_docs(config)
+end
+
+def stub_route(verb, action, controller, spec)
+  double("route", :verb => double("verb", :source => verb),
+    :defaults => {:action => action, :controller => controller},
+    :path => double("path", :spec => spec)
+  )
+end
+
+def get_api_paths(apis, path)
+  apis.select{|api| api["path"] == path}
+end
+
+def get_api_operations(apis, path)
+  apis = get_api_paths(apis, path)
+  apis.collect{|api| api["operations"]}.flatten
+end
+
+def get_api_operation(apis, path, method)
+  operations = get_api_operations(apis, path)
+  operations.each{|operation| return operation if operation["method"] == method.to_s}
+end
+
+def get_api_parameter(api, name)
+  api["parameters"].each{|param| return param if param["name"] == name}
+end
+

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: swagger-docs
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Rich Hollis
@@ -30,7 +30,7 @@ cert_chain:
   RYcsqDfanYBx7QcftOnbeQq7/Ep7Zx+W9+Ph3TiJLMLdAr7bLkgN1SjvrjTL5mQR
   FuQtYvE4LKiUQpG7vLTRB78dQBlSj9fnv2OM9w==
   -----END CERTIFICATE-----
-date: 2014-02-14 00:00:00.000000000 Z
+date: 2014-04-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler

metadata.gz.sig

@@ -1,3 +1 @@
-D���v�v���"���o���/C˞�/rc��HU�>*7�6�T;UCap��F�4�H��j��#u�|5�V���nt0��������ن�Γ���L5�G���cΞ�j������=t �悰[B��I۾�:+76�}���[ݙcXL���͸v�����dl�
-6`�����ѽ��m����p���֌��������l��+�XK|`1�ds�B�{ɫœ1'�.m��i��f�7�qY��
-��tpS�
�
+��Í��%��eb�D�',�gk��yf�8_*�@��v@H�4ȴ �)s�ҥ�?Ȏ�aQ��UO�'��|�|*���Z�p���/ݾ7�g
L���L*����u��w�LƗ��F\�8���?��_�h��6���R�1Y�?m��dp��b�)>ܝكZa��,�p;pw��e@W��p��0�Ӵ�[ʦo�����h�MK��}�G�2��LN���*��Jz)�9-�w��4�e+�3ϝ�>��/�?xc�Ѧ�A}�