swagger-docs 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a75950a4aa93348fac017729155424b1874af4fd
-  data.tar.gz: 4e5999ac0013e7d6e97576266a389ffad061ae3d
+  metadata.gz: f824965e424cbfdcd8551dea96dbabe88e7368fd
+  data.tar.gz: 2a02f6c05ea8aa87659b022f4807bf2a9874639f
 SHA512:
-  metadata.gz: 3ecb1013e18dba07d1ce736e0f0013fe8e55c1fd60e5e05a17a14e3a8ec745ff4f24fd0aa2fbb20ab1495390121657be931d3bceb8a77f0e0e98d237923f04e3
-  data.tar.gz: 41b87d5d7faa0d941cb2ef509099679ceb9ab5ee8c6d4814fc77239e3a69ec7314386cfee936084e76995d5e3fb26b231b4e51a992de33c08dac5cc4f8620adb
+  metadata.gz: 81971dd258cb50fae6a2a0e8c6837deff20da9f9067e6a4a433b6c04e4a3351fa035d59871fb263f96bae53db2164b9b053013d487e427129619ad3956c7b8bd
+  data.tar.gz: 817550eddc45f754818bebdfa134fc6bff885a6fa6796116bf2f7da4530bba0458f2cc076e569d16dc602129177c14f7969bb8ca3b7a33eb9f0f8a4a80a950e5

data/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.1.1
+- Add support for Rails engines (@fotinakis)
+- Filter out path parameters if the parameter is not in the path (@stevschmid)
+
 ## 0.1.0
 
 - Add CHANGELOG.md
@@ -8,6 +12,7 @@
 - Custom response message error text can now be set
 - Ability to override base controller with `base_api_controller` method
 - Default configuration for Generator
+- Fix typo in README.md
 
 ##0.0.3
 

data/README.md

@@ -183,6 +183,34 @@ class Swagger::Docs::Config
 end
 ```
 
+#### Custom route discovery for supporting Rails Engines
+
+By default, swagger-docs finds controllers by traversing routes in `Rails.application`.
+To override this, you can customize the `base_application` config in an initializer:
+
+```ruby
+class Swagger::Docs::Config
+  def self.base_application; Api::Engine end
+end
+```
+
+=======
+#### Transforming the `path` variable
+
+Swagger allows a distinction between the API documentation server and the hosted API
+server through the `path` variable (see [Swagger: No server Integrations](https://github.com/wordnik/swagger-core/wiki/No-server-Integrations)). To override the default swagger-docs behavior, you can provide a `transform_path`
+class method in your initializer:
+
+```ruby
+class Swagger::Docs::Config
+  def self.transform_path(path)
+    "http://example.com/api-docs/#{path}"
+  end
+end
+```
+
+The transformation will be applied to all API `path` values in the generated `api-docs.json` file.
+
 #### Precompile
 
 It is best-practice *not* to keep documentation in version control. An easy way

data/lib/swagger/docs/config.rb

@@ -3,6 +3,7 @@ module Swagger
     class Config
       class << self
         def base_api_controller; ApplicationController end
+        def base_application; Rails.application end
         def register_apis(versions)
           base_api_controller.send(:include, ImpotentMethods)
           @versions = versions
@@ -10,6 +11,10 @@ module Swagger
         def registered_apis
           @versions ||= {}
         end
+        def transform_path(path)
+          # This is only for overriding, so don't perform any path transformations by default.
+          path
+        end
       end
     end
   end

data/lib/swagger/docs/generator.rb

@@ -4,9 +4,9 @@ module Swagger
 
       DEFAULT_VER = "1.0"
       DEFAULT_CONFIG = {
-        :api_file_path => "public/", 
-        :base_path => "/", 
-        :clean_directory => false, 
+        :api_file_path => "public/",
+        :base_path => "/",
+        :clean_directory => false,
         :formatting => :pretty
       }
 
@@ -91,7 +91,7 @@ module Swagger
           header = { :api_version => api_version, :swagger_version => "1.2", :base_path => base_path + "/"}
           resources = header.merge({:apis => []})
 
-          paths = Rails.application.routes.routes.map{|i| "#{i.defaults[:controller]}" }
+          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?
@@ -102,14 +102,16 @@ module Swagger
             end
             apis = []
             debased_path = path.gsub("#{controller_base_path}", "")
-            Rails.application.routes.routes.select{|i| i.defaults[:controller] == path}.each do |route|
+            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] }] # rename :@instance hash keys
+              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}"
-              apis << {:path => trim_slashes(get_api_path(trim_leading_slash(route.path.spec.to_s), config[:api_extension_type]).gsub("#{controller_base_path}","")), :operations => [operations]}
+              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})
@@ -117,7 +119,7 @@ module Swagger
             # 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: "#{trim_leading_slash(debased_path)}.{format}", description: klass.swagger_config[:description]}
+            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
@@ -134,6 +136,15 @@ module Swagger
           end
           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]}}"
+            param[:param_type] == :path && !path.include?(param_as_variable)
+          end
+        end
       end
     end
   end

data/lib/swagger/docs/methods.rb

@@ -29,11 +29,11 @@ module Swagger
           @swagger_dsl ||= {}
           controller_action = "#{name}##{action} #{self.class}"
           return if @swagger_dsl[action]
-          route = Rails.application.routes.routes.select{|i| "#{i.defaults[:controller].to_s.camelize}Controller##{i.defaults[:action]}" == controller_action }.first
+          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
       end
     end
   end
-end
+end

data/lib/swagger/docs/version.rb

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

data/spec/fixtures/controllers/sample_controller.rb

@@ -8,6 +8,7 @@ module Api
       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, "The request you made is not acceptable"
         response :requested_range_not_satisfiable

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

@@ -23,6 +23,7 @@ describe Swagger::Docs::Generator do
   let(:routes) {[
     stub_route("^GET$", "index", "api/v1/ignored", "/api/v1/ignored(.:format)"),
     stub_route("^GET$", "index", "api/v1/sample", "/api/v1/sample(.:format)"),
+    stub_route("^GET$", "index", "api/v1/sample", "/api/v1/nested/:nested_id/sample(.:format)"),
     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)"),
@@ -67,7 +68,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 5
+        expect(response["apis"].count).to eq 6
       end
       context "first api" do
         #"apis":[{"path":" /sample","operations":[{"summary":"Fetches all User items"
@@ -168,8 +169,7 @@ describe Swagger::Docs::Generator do
       context "resource file" do
         let(:resource) { FILE_RESOURCE.read }
         let(:response) { JSON.parse(resource) }
-        let(:first) { response["apis"].first }
-        let(:operations) { first["operations"] }
+        let(:operations) { api["operations"] }
         let(:params) { operations.first["parameters"] }
         let(:response_msgs) { operations.first["responseMessages"] }
         # {"apiVersion":"1.0","swaggerVersion":"1.2","basePath":"/api/v1","resourcePath":"/sample"
@@ -186,18 +186,19 @@ 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 5
+          expect(response["apis"].count).to eq 6
         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(first["path"]).to eq "sample"
+            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(first["path"]).to eq "sample.json"
+            expect(api["path"]).to eq "sample.json"
           end
           it "writes summary correctly" do
             expect(operations.first["summary"]).to eq "Fetches all User items"
@@ -208,7 +209,10 @@ describe Swagger::Docs::Generator do
           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}]
+          #"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
@@ -245,6 +249,14 @@ describe Swagger::Docs::Generator do
             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
+          end
+        end
       end
     end
   end

metadata

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

metadata.gz.sig

@@ -1,3 +1,3 @@
-[u���
-���� ��Q��7*<�^#�n4
-�rn
7��(����}m�N�[t$*} ���������ޞ˶^9�Iȅ�#�L���=�\�ʆd~��cߵ�V�|7����s�������!�d�x\�MuC�N�v
(�pnv�����o?8�Օz����P
+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�
�