swagger-docs 0.1.5 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 67c64b2ae7bcb8d0a653d598dc5f6de70d223d8e
-  data.tar.gz: 95555f61513a11238944a1e9a4bd361f00e70159
+  metadata.gz: 17bc5fa1520eb501616e867896c0f7f7000c31fd
+  data.tar.gz: 068f350b226c8fc91d300fce8fd1ac9770ee694e
 SHA512:
-  metadata.gz: c047b999407fc51017a1e6ded45582bff68c395446f643d3aaef3f2c3f0c5d397cc6f210c9021348337bce459b5f5e2d88a9eb6ac98814826fd86746b6046f14
-  data.tar.gz: 2a86f256d2298cb7ab8abadd4e350641bb37da943f77b1dad6f7cb2b1d7106b942b6d55c8efb39636c755464f7fec03a7d20effe3c655b37b96b9aaf2093e0c6
+  metadata.gz: 0ea1c7020b0b029f3d897a2c21fb6b72850bb64358d789473ef2bcba346da34e1b730f216435b42f5767742d3bd7e79da19e3c3d38c697402920688e0dc55f0c
+  data.tar.gz: a38e70b6f391db69f06676372ffd1dab18ecebc9c042bea9844221ada5bf2196ccf8610e026d73df108e7b43f5b555641a64ca4dad52d4b99036a34abf1a8a49

data/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 0.1.6
+
+- Document notes DSL
+- Get rid of unnecessary ternary operator in dsl.rb #54
+- Fix development dependencies gems requirements #53
+- Add support for the `notes` property #52
+- Config's base_api_controller is configurable #51
+
 ## 0.1.5
 - Delay processing docs DSL to allow changing the context of the controllers #47 @ldnunes
 

data/README.md

@@ -9,6 +9,7 @@ swagger_controller :users, "User Management"
 
 swagger_api :index do
   summary "Fetches all User items"
+  notes "This lists all the active users"
   param :query, :page, :integer, :optional, "Page number"
   response :unauthorized
   response :not_acceptable
@@ -83,6 +84,12 @@ The following table shows all the current configuration options and their defaul
 <td>/</td>
 </tr>
 
+<tr>
+<td><b>base_api_controller</b></td>
+<td>The base controller class your project uses; it or its subclasses will be where you call swagger_controller and swagger_api.</td>
+<td>ActionController::Base</td>
+</tr>
+
 <tr>
 <td><b>clean_directory</b></td>
 <td>When generating swagger-docs files this option specifies if the api_file_path should be cleaned first. This means that all files will be deleted in the output directory first before any files are generated.</td>
@@ -108,6 +115,7 @@ class Api::V1::UsersController < ApplicationController
 
   swagger_api :index do
     summary "Fetches all User items"
+    notes "This lists all the active users"
     param :query, :page, :integer, :optional, "Page number"
     param :path, :nested_id, :integer, :optional, "Team Id"
     response :unauthorized
@@ -163,6 +171,36 @@ class Api::V1::UsersController < ApplicationController
 end
 ```
 
+### DRYing up common documentation
+
+Suppose you have a header or a parameter that must be present on several controllers and methods. Instead of duplicating it on all the controllers you can do this on your API base controller:
+ 
+```ruby
+class Api::BaseController < ActionController::Base
+  class << self
+    Swagger::Docs::Generator::set_real_methods
+ 
+    def inherited(subclass)
+      super
+      subclass.class_eval do
+        setup_basic_api_documentation
+      end
+    end
+ 
+    private
+    def setup_basic_api_documentation
+      [:index, :show, :create, :update, :delete].each do |api_action|
+        swagger_api api_action do
+          param :header, 'Authentication-Token', :string, :required, 'Authentication token'
+        end
+      end
+    end
+  end
+end
+```
+ 
+And then use it as a superclass to all you API controllers. All the subclassed controllers will have the same documentation applied to them.
+
 ### DSL Methods
 
 <table>
@@ -179,6 +217,11 @@ end
 <td>The summary of the API</td>
 </tr>
 
+<tr>
+<td>notes (optional)</td>
+<td>The associated notes for the API</td>
+</tr>
+
 <tr>
 <td>param</td>
 <td>Standard API Parameter</td>
@@ -216,35 +259,6 @@ https://github.com/richhollis/swagger-docs-sample
 
 ### Advanced Customization
 
-#### Recurring parameters
-
-If you have lots of recurring parameters then you can use this approach suggested by Lucas Dutra Nunes (@ldnunes):
-
-```
-class Api::BaseController < ActionController::Base
-  class << self
-    Swagger::Docs::Generator::set_real_methods
-
-    def inherited(subclass)
-      super
-      subclass.class_eval do
-        setup_basic_api_documentation
-      end
-    end
-
-    private
-
-    def setup_basic_api_documentation
-      [:index, :show, :create, :update, :delete].each do |api_action|
-        swagger_api api_action do
-          param :header, 'Authentication-Token', :string, :required, 'Authentication token'
-        end
-      end
-    end
-  end
-end
-```
-
 #### Inheriting from a custom Api controller
 
 By default swagger-docs is applied to controllers inheriting from ApplicationController.
@@ -598,6 +612,8 @@ Thanks to jdar, fotinakis, stevschmid, ldnunes and all of our contributors for m
 
 ## Contributing
 
+When raising a Pull Request please ensure that you have provided good test coverage for the request you are making.
+
 1. Fork it
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Commit your changes (`git commit -am 'Add some feature'`)

data/lib/swagger/docs/config.rb

@@ -2,15 +2,29 @@ module Swagger
   module Docs
     class Config
       class << self
-        def base_api_controller; ActionController::Base end
-        def base_application; Rails.application end
+        @@base_api_controller = nil
+
+        def base_api_controller
+          @@base_api_controller || ActionController::Base
+        end
+
+        def base_api_controller=(controller)
+          @@base_api_controller = controller
+        end
+
+        def base_application
+          Rails.application 
+        end
+
         def register_apis(versions)
           base_api_controller.send(:include, ImpotentMethods)
           @versions = versions
         end
+
         def registered_apis
           @versions ||= {}
         end
+        
         def transform_path(path)
           # This is only for overriding, so don't perform any path transformations by default.
           path

data/lib/swagger/docs/dsl.rb

@@ -16,6 +16,10 @@ module Swagger
       def summary(text)
         @summary = text
       end
+      
+      def notes(text)
+        @notes = text
+      end
 
       def method(method)
         @method = method
@@ -35,7 +39,7 @@ module Swagger
 
       def param(param_type, name, type, required, description = nil, hash={})
         parameters << {:param_type => param_type, :name => name, :type => type,
-          :description => description, :required => required == :required ? true : false}.merge(hash)
+          :description => description, :required => required == :required}.merge(hash)
       end
 
       # helper method to generate enums
@@ -93,7 +97,7 @@ module Swagger
           type: type,
           description: description,
         }.merge!(hash)
-        self.required << name if (required == :required ? true : false)
+        self.required << name if required == :required
       end
     end
   end

data/lib/swagger/docs/generator.rb

@@ -62,8 +62,7 @@ module Swagger
             ret = process_path(path, root, config, settings)
             results[ret[:action]] << ret
             if ret[:action] == :processed
-              resource = generate_resource(ret[:path], ret[:apis], ret[:models], settings, root, config)
-              resources << resource
+              resources << generate_resource(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}",

data/lib/swagger/docs/version.rb

@@ -1,5 +1,5 @@
 module Swagger
   module Docs
-    VERSION = "0.1.5"
+    VERSION = "0.1.6"
   end
 end

data/spec/fixtures/controllers/sample_controller.rb

@@ -40,6 +40,7 @@ module Api
 
       swagger_api :update do
         summary "Updates an existing User"
+        notes "Only the given fields are updated."
         param :path, :id, :integer, :required, "User Id"
         param :form, :first_name, :string, :optional, "First name"
         param :form, :last_name, :string, :optional, "Last name"

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

@@ -0,0 +1,31 @@
+require 'spec_helper'
+
+describe Swagger::Docs::Config do
+
+  require "fixtures/controllers/application_controller"
+
+  let(:test_controller) { Class.new }
+
+  before(:each) do 
+    stub_const('ActionController::Base', ApplicationController)
+  end
+
+  subject { Swagger::Docs::Config }
+
+  describe "::base_api_controller" do
+    it "returns ActionController::Base by default" do
+      expect(subject.base_api_controller).to eq(ActionController::Base)
+    end
+    it "allows assignment of another class" do
+      subject.base_api_controller = test_controller
+      expect(subject.base_api_controller).to eq(test_controller)
+    end 
+  end
+
+  describe "::base_application" do
+    it "defaults to Rails.application" do
+      expect(subject.base_application).to eq (Rails.application)
+    end
+  end
+
+ end

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

@@ -34,7 +34,7 @@ describe Swagger::Docs::Generator do
       }
     }
     before(:each) do
-      Rails.stub_chain(:application, :routes, :routes).and_return(routes)
+      allow(Rails).to receive_message_chain(:application, :routes, :routes).and_return(routes)
       Swagger::Docs::Generator.set_real_methods
       require "fixtures/controllers/sample_controller"
       generate(config)
@@ -83,7 +83,7 @@ describe Swagger::Docs::Generator do
     })}
     let(:file_resource) { tmp_dir + 'sample.json' }
     before(:each) do
-      Rails.stub_chain(:application, :routes, :routes).and_return(routes)
+      allow(Rails).to receive_message_chain(:application, :routes, :routes).and_return(routes)
       Swagger::Docs::Generator.set_real_methods
       require "fixtures/controllers/sample_controller"
     end
@@ -248,7 +248,7 @@ describe Swagger::Docs::Generator do
                 expect(params.first["description"]).to eq "Page number"
               end
               it "writes required correctly" do
-                expect(params.first["required"]).to be_false
+                expect(params.first["required"]).to be_falsey
               end
             end
             #"responseMessages":[{"code":401,"message":"Unauthorized"},{"code":406,"message":"Not Acceptable"},{"code":416,"message":"Requested Range Not Satisfiable"}]
@@ -286,6 +286,9 @@ describe Swagger::Docs::Generator do
           end
           context "update" do
             let(:api) { get_api_operation(apis, "sample/{id}", :put) }
+            it "writes notes correctly" do
+              expect(api["notes"]).to eq "Only the given fields are updated."
+            end
             it "writes model param correctly" do
               expected_param = {
                 "paramType" => "form",

data/spec/spec_helper.rb

@@ -10,7 +10,11 @@ RSpec.configure do |config|
   config.expect_with :rspec do |c|
     c.syntax = :expect
   end
-  config.color_enabled = true
+  config.color = true
+
+  config.before(:each) do
+    Swagger::Docs::Config.base_api_controller = nil # use default object
+  end
 end
 
 def generate(config)

data/swagger-docs.gemspec

@@ -23,8 +23,8 @@ Gem::Specification.new do |spec|
   spec.signing_key = File.expand_path("~/.gemcert/gem-private_key.pem") if $0 =~ /gem\z/
 
   spec.add_development_dependency "bundler", "~> 1.3"
-  spec.add_development_dependency "rake",  "~> 0"
-  spec.add_development_dependency "rspec",  "~> 0"
-  spec.add_development_dependency "rails",  "~> 0"
-  spec.add_development_dependency "appraisal",  "~> 0"
+  spec.add_development_dependency "rake", "~> 10"
+  spec.add_development_dependency "rspec", "= 3.0.0beta2"
+  spec.add_development_dependency "rails", ">= 3"
+  spec.add_development_dependency "appraisal", ">= 1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: swagger-docs
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.1.6
 platform: ruby
 authors:
 - Rich Hollis
@@ -30,7 +30,7 @@ cert_chain:
   RYcsqDfanYBx7QcftOnbeQq7/Ep7Zx+W9+Ph3TiJLMLdAr7bLkgN1SjvrjTL5mQR
   FuQtYvE4LKiUQpG7vLTRB78dQBlSj9fnv2OM9w==
   -----END CERTIFICATE-----
-date: 2014-04-28 00:00:00.000000000 Z
+date: 2014-05-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -52,56 +52,56 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '10'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '10'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - '='
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 3.0.0beta2
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - '='
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 3.0.0beta2
 - !ruby/object:Gem::Dependency
   name: rails
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '3'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '3'
 - !ruby/object:Gem::Dependency
   name: appraisal
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '1'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '1'
 description: Generates json files for rails apps to use with swagger-ui
 email:
 - richhollis@gmail.com
@@ -129,6 +129,7 @@ files:
 - spec/fixtures/controllers/application_controller.rb
 - spec/fixtures/controllers/ignored_controller.rb
 - spec/fixtures/controllers/sample_controller.rb
+- spec/lib/swagger/docs/config_spec.rb
 - spec/lib/swagger/docs/generator_spec.rb
 - spec/spec_helper.rb
 - swagger-docs.gemspec
@@ -161,5 +162,6 @@ test_files:
 - spec/fixtures/controllers/application_controller.rb
 - spec/fixtures/controllers/ignored_controller.rb
 - spec/fixtures/controllers/sample_controller.rb
+- spec/lib/swagger/docs/config_spec.rb
 - spec/lib/swagger/docs/generator_spec.rb
 - spec/spec_helper.rb

metadata.gz.sig

@@ -1 +1 @@
-�aS9!fI}ª �@
+,|�e�m����}�z�������m��]ȿ8V��3V���A�Z����YE�΅|~�,/_,sOׄ�>�4ۿ��3�}|�S$ը�` 0 �n�Ӷ+��5N[o�"�N%�]6]�túz�}�ݩ�Z\��q�����;ep�2O8$�}������\b��yLh������3$�B�;��DJ�S��'�"���FeCۂ�F������[��n=���o��zQlC_)���η`XA+W�	�� W�m�L8c����