swagger-docs 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8288447cb546d04ee3e791e473f06351c1f9e702
-  data.tar.gz: cf69d2574759663cdccb895d4c320c0b085fa0e4
+  metadata.gz: 93662e19d54d8714102ecfbd08e1ca88e360cd00
+  data.tar.gz: 646f03361ada42fc36e8369bc602e00307b86b0d
 SHA512:
-  metadata.gz: 0cfdeb3b6ffc0c27f2306739d7831496c65c480efd54ad583923b5c0d1a5e6aa12643f55e59ffe4797e71b87f7d29fdba49c8f5d866f167906cc1e113f4be7a1
-  data.tar.gz: aa89d0b6b9cac77cd1b9ab5e952b89ce3c85bed99fdc0933e891ba9bcf633180ffc72e6e1ba82e1dfbb197fdb261efafbdc66970f83dbfe474073894716aa6f2
+  metadata.gz: 868a3e56fc30ccee2ee8e636ab800d21398f4d5f4b0d8bf7867a302471e9c66841841a2332159f4e61a8311852b6bf9d437ff6135d685d60e6f04abedc0d2aad
+  data.tar.gz: 709e92e1acbee458adfd53facc2f2be17308f6dfca0bfd7a6213eceb232d447686e8aea79d16a7d4e3e4f2e8c874e1b8a23ed2e6e052f6980cfefe44acfa0008

data/README.md

@@ -38,14 +38,18 @@ Create an initializer in config/initializers (e.g. swagger_docs.rb) and define y
 
 ```
 Swagger::Docs::Config.register_apis({
-  "1.0" => {:controller_base_path => "api/v1", :api_file_path => "public/api/v1/", :base_path => "http://api.somedomain.com"}
-})
+  "1.0" => {
+    :api_file_path => "public/api/v1/", # the output location where your .json files are written to
+    :base_path => "http://api.somedomain.com", # the URL base path to your API 
+    :clean_directory => false # if you want to delete all .json files at each generation
+  }
+)
 ```
 
 ### Documenting a controller
 
 ```
-class Api::V1::UsersController < ApiController
+class Api::V1::UsersController < ApplicationController
 
   swagger_controller :users, "User Management"
 
@@ -101,7 +105,15 @@ end
 rake swagger:docs
 ```
 
-### Swagger-ui JSON files should now be present in your api_file_path (e.g. ./public/api/v1)
+Swagger-ui JSON files should now be present in your api_file_path (e.g. ./public/api/v1)
+
+### Sample 
+
+A sample Rails application where you can run the above rake command and view the output in swagger-ui can be found here:
+
+https://github.com/richhollis/swagger-docs-sample
+
+### Output files
 
 api-docs.json output:
 

data/lib/swagger/docs/generator.rb

@@ -18,7 +18,7 @@ module Swagger
         end
 
         def get_api_path(spec)
-          path_api = spec.to_s.gsub("(.:format)", "")
+          path_api = trim_leading_slash(spec.to_s.gsub("(.:format)", ""))
           parts_new = []
           path_api.split("/").each do |path_part|
             part = path_part
@@ -31,6 +31,22 @@ module Swagger
           path_api = parts_new*"/"
         end
 
+        def trim_leading_slash(str)
+          return str if !str
+          return str unless str[0] == '/'
+          str[1..-1]
+        end
+
+        def trim_trailing_slash(str)
+          return str if !str
+          return str unless str[-1] == '/'
+          str[0..-2]
+        end
+
+        def trim_slashes(str)
+          trim_leading_slash(trim_trailing_slash(str))
+        end
+
         def set_real_methods
           ApplicationController.send(:include, Methods) # replace impotent methods with live ones
         end
@@ -38,33 +54,44 @@ module Swagger
         def write_docs(apis)
           results = {}
           set_real_methods
-          Config.registered_apis.each do |api_version,config|
-            results[api_version] = write_doc(api_version, config)
+          unless Config.registered_apis.empty?
+            Config.registered_apis.each do |api_version,config|
+              results[api_version] = write_doc(api_version, config)
+            end
+          else
+            config = {:api_file_path => "public/", :base_path => "/"}
+            puts "No swagger_docs config: Using default config #{config}"
+            results["1.0"] = write_doc("1.0", config)
           end
           results
         end
 
         def write_doc(api_version, config)
-          base_path = config[:base_path]
-          controller_base_path = config[:controller_base_path]
+          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 => []}
 
+          # 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)} # clean 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
 
-          header = { :api_version => api_version, :swagger_version => "1.2", :base_path => "#{base_path}/#{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 => []})
 
           paths = Rails.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}", "")
             Rails.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
@@ -72,20 +99,20 @@ module Swagger
               operations = Hash[operations.map {|k, v| [k.to_s.gsub("@","").to_sym, v] }] # rename :@instance hash keys
               operations[:method] = verb
               operations[:nickname] = "#{path.camelize}##{action}"
-              apis << {:path => get_api_path(route.path.spec).gsub("/#{controller_base_path}",""), :operations => [operations]}
+              apis << {:path => trim_slashes(get_api_path(trim_leading_slash(route.path.spec.to_s)).gsub("#{controller_base_path}","")), :operations => [operations]}
             end
-            demod = "#{path.to_s.camelize}".demodulize.camelize.underscore
-            resource = header.merge({:resource_path => "/#{demod}", :apis => apis})
+            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
-            File.open("#{api_file_path}#{demod}.json", 'w') { |file| file.write(resource.to_json) }
+            File.open("#{api_file_path}/#{demod}.json", 'w') { |file| file.write(resource.to_json) }
             # append resource to resources array (for writing out at end)
-            resources[:apis] << {path: "/#{demod}.{format}", description: klass.swagger_config[:description]}
+            resources[:apis] << {path: "#{trim_leading_slash(debased_path)}.{format}", description: klass.swagger_config[:description]}
             results[:processed] << path
           end
           # write master resource file
           camelize_keys_deep!(resources)
-          File.open("#{api_file_path}api-docs.json", 'w') { |file| file.write(resources.to_json) }
+          File.open("#{api_file_path}/api-docs.json", 'w') { |file| file.write(resources.to_json) }
           results
         end
       end

data/lib/swagger/docs/version.rb

@@ -1,5 +1,5 @@
 module Swagger
   module Docs
-    VERSION = "0.0.2"
+    VERSION = "0.0.3"
   end
 end

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

@@ -5,6 +5,10 @@ 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},
@@ -14,67 +18,38 @@ describe Swagger::Docs::Generator do
 
   before(:each) do
     FileUtils.rm_rf(TMP_DIR)
-    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("^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)")
-    ]
-    @config = Swagger::Docs::Config.register_apis({
-      "1.0" => {:controller_base_path => "api/v1", :api_file_path => "#{TMP_DIR}api/v1/", :base_path => "http://api.no.where"}
-    })
-    Rails.stub_chain(:application, :routes, :routes).and_return(routes)
-    Swagger::Docs::Generator.set_real_methods
-    require "fixtures/controllers/sample_controller"
   end
 
-  context "test suite initialization" do
-    it "the resources file does not exist" do
-      expect(File.exists?(FILE_RESOURCES)).to be_false
-    end
-    it "the resource file does not exist" do
-      expect(File.exists?(FILE_RESOURCE)).to be_false
-    end
-  end
+  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("^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)")
+  ]}
 
-  describe "#write_docs" do
-    let(:generate) { Swagger::Docs::Generator::write_docs(@config) }
+  context "without controller base path" do
+    let(:config) { Swagger::Docs::Config.register_apis({
+        "1.0" => {:api_file_path => "#{TMP_DIR}api/v1/", :base_path => "http://api.no.where"}
+      })}
     before(:each) do
-      generate
-    end
-    it "writes the resources file" do
-      expect(File.exists?(FILE_RESOURCES)).to be_true
-    end
-    it "writes the resource file" do
-      expect(File.exists?(FILE_RESOURCE)).to be_true
-    end
-    it "returns results hash" do
-      results = generate
-      expect(results["1.0"][:processed].count).to eq 1
-      expect(results["1.0"][:skipped].count).to eq 1
+      Rails.stub_chain(:application, :routes, :routes).and_return(routes)
+      Swagger::Docs::Generator.set_real_methods
+      require "fixtures/controllers/sample_controller"
+      generate(config)
     end
     context "resources files" do
       let(:resources) { File.read(FILE_RESOURCES)}
       let(:response) { JSON.parse(resources) }
-      it "writes version correctly" do
-        expect(response["apiVersion"]).to eq "1.0"
-      end
-      it "writes swaggerVersion correctly" do
-        expect(response["swaggerVersion"]).to eq "1.2"
-      end
       it "writes basePath correctly" do
-        expect(response["basePath"]).to eq "http://api.no.where/api/v1"
+        expect(response["basePath"]).to eq "http://api.no.where/"
       end
       it "writes apis correctly" do
         expect(response["apis"].count).to eq 1
       end
       it "writes api path correctly" do
-        expect(response["apis"][0]["path"]).to eq "/sample.{format}"
-      end
-      it "writes api description correctly" do
-        expect(response["apis"][0]["description"]).to eq "User Management"
+        expect(response["apis"][0]["path"]).to eq "api/v1/sample.{format}"
       end
     end
     context "resource file" do
@@ -82,20 +57,12 @@ describe Swagger::Docs::Generator do
       let(:response) { JSON.parse(resource) }
       let(:first) { response["apis"].first }
       let(:operations) { first["operations"] }
-      let(:params) { operations.first["parameters"] }
-      let(:response_msgs) { operations.first["responseMessages"] }
       # {"apiVersion":"1.0","swaggerVersion":"1.2","basePath":"/api/v1","resourcePath":"/sample"
-      it "writes version correctly" do
-        expect(response["apiVersion"]).to eq "1.0"
-      end
-      it "writes swaggerVersion correctly" do
-        expect(response["swaggerVersion"]).to eq "1.2"
-      end
       it "writes basePath correctly" do
-        expect(response["basePath"]).to eq "http://api.no.where/api/v1"
+        expect(response["basePath"]).to eq "http://api.no.where/"
       end
       it "writes resourcePath correctly" do
-        expect(response["resourcePath"]).to eq "/sample"
+        expect(response["resourcePath"]).to eq "sample"
       end
       it "writes out expected api count" do
         expect(response["apis"].count).to eq 5
@@ -104,48 +71,153 @@ describe Swagger::Docs::Generator do
         #"apis":[{"path":" /sample","operations":[{"summary":"Fetches all User items"
         #,"method":"get","nickname":"Api::V1::Sample#index"}]
         it "writes path correctly" do
-          expect(first["path"]).to eq "/sample"
+          expect(first["path"]).to eq "api/v1/sample"
+        end
+      end
+    end
+  end
+
+  context "with controller base path" do
+    let(:config) { Swagger::Docs::Config.register_apis({
+      "1.0" => {:controller_base_path => "api/v1", :api_file_path => "#{TMP_DIR}api/v1/", :base_path => "http://api.no.where"}
+    })}
+    before(:each) do 
+      Rails.stub_chain(:application, :routes, :routes).and_return(routes)
+      Swagger::Docs::Generator.set_real_methods
+      require "fixtures/controllers/sample_controller"
+    end
+
+    context "test suite initialization" do
+      it "the resources file does not exist" do
+        expect(File.exists?(FILE_RESOURCES)).to be_false
+      end
+      it "the resource file does not exist" do
+        expect(File.exists?(FILE_RESOURCE)).to be_false
+      end
+    end
+
+    describe "#write_docs" do
+      before(:each) do
+        generate(config)
+      end
+      it "cleans json files in directory when set" do
+        file_to_delete = "#{TMP_DIR}api/v1/delete_me.json"
+        File.open(file_to_delete, 'w') {|f| f.write("{}") }
+        expect(File.exists?(file_to_delete)).to be_true
+        config["1.0"][:clean_directory] = true
+        generate(config)
+        expect(File.exists?(file_to_delete)).to be_false
+      end
+      it "keeps non json files in directory when cleaning" do
+        file_to_keep = "#{TMP_DIR}api/v1/keep_me"
+        File.open(file_to_keep, 'w') {|f| f.write("{}") }
+        config["1.0"][:clean_directory] = true
+        generate(config)
+        expect(File.exists?(file_to_keep)).to be_true
+      end
+      it "writes the resources file" do
+        expect(File.exists?(FILE_RESOURCES)).to be_true
+      end
+      it "writes the resource file" do
+        expect(File.exists?(FILE_RESOURCE)).to be_true
+      end
+      it "returns results hash" do
+        results = generate(config)
+        expect(results["1.0"][:processed].count).to eq 1
+        expect(results["1.0"][:skipped].count).to eq 1
+      end
+      context "resources files" do
+        let(:resources) { File.read(FILE_RESOURCES)}
+        let(:response) { JSON.parse(resources) }
+        it "writes version correctly" do
+          expect(response["apiVersion"]).to eq "1.0"
         end
-        it "writes summary correctly" do
-          expect(operations.first["summary"]).to eq "Fetches all User items"
+        it "writes swaggerVersion correctly" do
+          expect(response["swaggerVersion"]).to eq "1.2"
         end
-        it "writes method correctly" do
-          expect(operations.first["method"]).to eq "get"
+        it "writes basePath correctly" do
+          expect(response["basePath"]).to eq "http://api.no.where/api/v1/"
         end
-        it "writes nickname correctly" do
-          expect(operations.first["nickname"]).to eq "Api::V1::Sample#index"
+        it "writes apis correctly" do
+          expect(response["apis"].count).to eq 1
         end
-        #"parameters":[{"paramType":"query","name":"page","type":"integer","description":"Page number","required":false}]
-        context "parameters" do
-          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"
+        it "writes api path correctly" do
+          expect(response["apis"][0]["path"]).to eq "sample.{format}"
+        end
+        it "writes api description correctly" do
+          expect(response["apis"][0]["description"]).to eq "User Management"
+        end
+      end
+      context "resource file" do
+        let(:resource) { File.read(FILE_RESOURCE)}
+        let(:response) { JSON.parse(resource) }
+        let(:first) { response["apis"].first }
+        let(:operations) { first["operations"] }
+        let(:params) { operations.first["parameters"] }
+        let(:response_msgs) { operations.first["responseMessages"] }
+        # {"apiVersion":"1.0","swaggerVersion":"1.2","basePath":"/api/v1","resourcePath":"/sample"
+        it "writes version correctly" do
+          expect(response["apiVersion"]).to eq "1.0"
+        end
+        it "writes swaggerVersion correctly" do
+          expect(response["swaggerVersion"]).to eq "1.2"
+        end
+        it "writes basePath correctly" do
+          expect(response["basePath"]).to eq "http://api.no.where/api/v1/"
+        end
+        it "writes resourcePath correctly" do
+          expect(response["resourcePath"]).to eq "sample"
+        end
+        it "writes out expected api count" do
+          expect(response["apis"].count).to eq 5
+        end
+        context "first api" do
+          #"apis":[{"path":" /sample","operations":[{"summary":"Fetches all User items"
+          #,"method":"get","nickname":"Api::V1::Sample#index"}]
+          it "writes path correctly" do
+            expect(first["path"]).to eq "sample"
           end
-          it "writes description correctly" do
-            expect(params.first["description"]).to eq "Page number"
+          it "writes summary correctly" do
+            expect(operations.first["summary"]).to eq "Fetches all User items"
           end
-          it "writes required correctly" do
-            expect(params.first["required"]).to be_false
+          it "writes method correctly" do
+            expect(operations.first["method"]).to eq "get"
           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
+          it "writes nickname correctly" do
+            expect(operations.first["nickname"]).to eq "Api::V1::Sample#index"
           end
-          it "writes code correctly" do
-            expect(response_msgs.first["code"]).to eq 401
+          #"parameters":[{"paramType":"query","name":"page","type":"integer","description":"Page number","required":false}]
+          context "parameters" do
+            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
-          it "writes message correctly" do
-            expect(response_msgs.first["message"]).to eq "Unauthorized"
+          #"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
+            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
           end
         end
       end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: swagger-docs
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors:
 - Rich Hollis
@@ -30,7 +30,7 @@ cert_chain:
   RYcsqDfanYBx7QcftOnbeQq7/Ep7Zx+W9+Ph3TiJLMLdAr7bLkgN1SjvrjTL5mQR
   FuQtYvE4LKiUQpG7vLTRB78dQBlSj9fnv2OM9w==
   -----END CERTIFICATE-----
-date: 2013-10-22 00:00:00.000000000 Z
+date: 2013-11-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler