swagger-docs 0.0.3 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 93662e19d54d8714102ecfbd08e1ca88e360cd00
-  data.tar.gz: 646f03361ada42fc36e8369bc602e00307b86b0d
+  metadata.gz: a75950a4aa93348fac017729155424b1874af4fd
+  data.tar.gz: 4e5999ac0013e7d6e97576266a389ffad061ae3d
 SHA512:
-  metadata.gz: 868a3e56fc30ccee2ee8e636ab800d21398f4d5f4b0d8bf7867a302471e9c66841841a2332159f4e61a8311852b6bf9d437ff6135d685d60e6f04abedc0d2aad
-  data.tar.gz: 709e92e1acbee458adfd53facc2f2be17308f6dfca0bfd7a6213eceb232d447686e8aea79d16a7d4e3e4f2e8c874e1b8a23ed2e6e052f6980cfefe44acfa0008
+  metadata.gz: 3ecb1013e18dba07d1ce736e0f0013fe8e55c1fd60e5e05a17a14e3a8ec745ff4f24fd0aa2fbb20ab1495390121657be931d3bceb8a77f0e0e98d237923f04e3
+  data.tar.gz: 41b87d5d7faa0d941cb2ef509099679ceb9ab5ee8c6d4814fc77239e3a69ec7314386cfee936084e76995d5e3fb26b231b4e51a992de33c08dac5cc4f8620adb

data/.gitignore

@@ -15,3 +15,4 @@ spec/reports
 test/tmp
 test/version_tmp
 tmp
+public

data/Appraisals

@@ -0,0 +1,7 @@
+appraise "rails-3" do
+  gem "rails", "~> 3.2.16"
+end
+
+appraise "rails-4" do
+  gem "rails", "~> 4.0.0"
+end

data/CHANGELOG.md

@@ -0,0 +1,22 @@
+## 0.1.0
+
+- Add CHANGELOG.md
+- Add `api_extension_type` option (support for other route .formats)
+- Rails Appraisals
+- Add configuration options table to README documentation
+- Guidance on inheritance and asset pre-compilation
+- Custom response message error text can now be set
+- Ability to override base controller with `base_api_controller` method
+- Default configuration for Generator
+
+##0.0.3
+
+- Documentation 
+
+## 0.0.2 
+
+- Add `base_path` option
+
+## 0.0.1 
+
+- Initial release

data/README.md

@@ -4,7 +4,7 @@ Generates swagger-ui json files for rails apps with APIs. You add the swagger DS
 
 Here is an extract of the DSL from a user controller API class:
 
-```
+```ruby
 swagger_controller :users, "User Management"
 
 swagger_api :index do
@@ -36,19 +36,72 @@ Or install it yourself as:
 
 Create an initializer in config/initializers (e.g. swagger_docs.rb) and define your APIs:
 
-```
+```ruby
 Swagger::Docs::Config.register_apis({
   "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
+    # 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", 
+    # if you want to delete all .json files at each generation
+    :clean_directory => false 
   }
-)
+})
 ```
 
+#### Configuration options
+
+The following table shows all the current configuration options and their defaults. The default will be used if you don't supply your own value.
+
+<table>
+<thead>
+<tr>
+<th>Option</th>
+<th>Description</th>
+<th>Default</th>
+</tr>
+</thead>
+<tbody>
+
+<tr>
+<td><b>api_extension_type</b></td>
+<td>The extension, if necessary, used for your API - e.g. :json or :xml </td>
+<td>nil</td>
+</tr>
+
+<tr>
+<td><b>api_file_path</b></td>
+<td>The output file path where generated swagger-docs files are written to. </td>
+<td>public/</td>
+</tr>
+
+<tr>
+<td><b>base_path</b></td>
+<td>The URI base path for your API - e.g. api.somedomain.com</td>
+<td>/</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>
+<td>false</td>
+</tr>
+
+<tr>
+<td><b>formatting</b></td>
+<td>Specifies which formatting method to apply to the JSON that is written. Available options: :none, :pretty</td>
+<td>:pretty</td>
+</tr>
+
+</tbody>
+</table>
+
+
 ### Documenting a controller
 
-```
+```ruby
 class Api::V1::UsersController < ApplicationController
 
   swagger_controller :users, "User Management"
@@ -113,12 +166,46 @@ A sample Rails application where you can run the above rake command and view the
 
 https://github.com/richhollis/swagger-docs-sample
 
+![Screen shot 1](https://github.com/richhollis/swagger-docs-sample/raw/master/swagger-docs-screenshot-2.png)
+
+
+### Advanced Customization
+
+#### 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 
+_before_ calling Swagger::Docs::Config#register_apis(...).
+
+```ruby
+class Swagger::Docs::Config
+  def self.base_api_controller; Api::ApiController end
+end
+```
+
+#### Precompile
+
+It is best-practice *not* to keep documentation in version control. An easy way
+to integrate swagger-docs into a conventional deployment setup (e.g. capistrano,
+chef, or opsworks) is to piggyback on the 'assets:precompile' rake task. And don't forget
+to add your api documentation directory to .gitignore in this case.
+
+```ruby
+#Rakefile or lib/task/precompile_overrides.rake
+namespace :assets do
+  task :precompile do
+    Rake::Task['assets:precompile'].invoke
+    Rake::Task['swagger:docs'].invoke
+  end
+end
+```
+
 ### Output files
 
 api-docs.json output:
 
 
-```
+```json
 {
   "apiVersion": "1.0",
   "swaggerVersion": "1.2",
@@ -134,7 +221,7 @@ api-docs.json output:
 
 users.json output:
 
-```
+```json
 {
   "apiVersion": "1.0",
   "swaggerVersion": "1.2",
@@ -337,6 +424,10 @@ users.json output:
 }
 ```
 
+## Thanks to our contributors
+
+Thanks to @jdar and all our contributors.
+
 ## Contributing
 
 1. Fork it

data/Rakefile

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

data/lib/swagger/docs/config.rb

@@ -2,8 +2,9 @@ module Swagger
   module Docs
     class Config
       class << self
+        def base_api_controller; ApplicationController end
         def register_apis(versions)
-          ApplicationController.send(:include, ImpotentMethods)
+          base_api_controller.send(:include, ImpotentMethods)
           @versions = versions
         end
         def registered_apis
@@ -12,4 +13,4 @@ module Swagger
       end
     end
   end
-end
+end

data/lib/swagger/docs/dsl.rb

@@ -45,7 +45,7 @@ module Swagger
       def response(status, text = nil, model = nil)
         if status.is_a? Symbol
           status_code = Rack::Utils.status_code(status)
-          response_messages << {:code => status_code, :message => status.to_s.titleize}
+          response_messages << {:code => status_code, :message => text || status.to_s.titleize}
         else
           response_messages << {:code => status, :message => text}
         end

data/lib/swagger/docs/generator.rb

@@ -1,6 +1,15 @@
 module Swagger
   module Docs
     class Generator
+
+      DEFAULT_VER = "1.0"
+      DEFAULT_CONFIG = {
+        :api_file_path => "public/", 
+        :base_path => "/", 
+        :clean_directory => false, 
+        :formatting => :pretty
+      }
+
       class << self
 
         def camelize_keys_deep!(h)
@@ -17,8 +26,9 @@ module Swagger
           end
         end
 
-        def get_api_path(spec)
-          path_api = trim_leading_slash(spec.to_s.gsub("(.:format)", ""))
+        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
@@ -48,20 +58,20 @@ module Swagger
         end
 
         def set_real_methods
-          ApplicationController.send(:include, Methods) # replace impotent methods with live ones
+          Config.base_api_controller.send(:include, Methods) # replace impotent methods with live ones
         end
 
-        def write_docs(apis)
+        def write_docs(apis = nil)
+          apis ||= Config.registered_apis
           results = {}
           set_real_methods
-          unless Config.registered_apis.empty?
-            Config.registered_apis.each do |api_version,config|
+          unless apis.empty?
+            apis.each do |api_version,config|
+              config.reverse_merge!(DEFAULT_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)
+            results[DEFAULT_VER] = write_doc(DEFAULT_VER, DEFAULT_CONFIG)
           end
           results
         end
@@ -99,23 +109,32 @@ 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 => trim_slashes(get_api_path(trim_leading_slash(route.path.spec.to_s)).gsub("#{controller_base_path}","")), :operations => [operations]}
+              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]}
             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
-            File.open("#{api_file_path}/#{demod}.json", 'w') { |file| file.write(resource.to_json) }
+            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]}
             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) }
+
+          write_to_file "#{api_file_path}/api-docs.json", resources, config
           results
         end
+
+        def write_to_file(path, structure, config={})
+          content = case config[:formatting]
+            when :pretty; JSON.pretty_generate structure
+            else;         structure.to_json
+          end
+          File.open(path, 'w') { |file| file.write content }
+        end
       end
     end
   end
-end
+end

data/lib/swagger/docs/version.rb

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

data/spec/fixtures/controllers/sample_controller.rb

@@ -1,14 +1,15 @@
 module Api
   module V1
-    class SampleController < ApplicationController
-
+    class SuperclassController < ApplicationController
+    end
+    class SampleController < SuperclassController
       swagger_controller :users, "User Management"
 
       swagger_api :index do
         summary "Fetches all User items"
         param :query, :page, :integer, :optional, "Page number"
         response :unauthorized
-        response :not_acceptable
+        response :not_acceptable, "The request you made is not acceptable"
         response :requested_range_not_satisfiable
       end
 
@@ -49,4 +50,4 @@ module Api
 
     end
   end
-end
+end

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

@@ -30,9 +30,11 @@ describe Swagger::Docs::Generator do
   ]}
 
   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"}
-      })}
+    let(:config) { 
+      {
+        DEFAULT_VER => {: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
@@ -40,7 +42,7 @@ describe Swagger::Docs::Generator do
       generate(config)
     end
     context "resources files" do
-      let(:resources) { File.read(FILE_RESOURCES)}
+      let(:resources) { FILE_RESOURCES.read }
       let(:response) { JSON.parse(resources) }
       it "writes basePath correctly" do
         expect(response["basePath"]).to eq "http://api.no.where/"
@@ -53,7 +55,7 @@ describe Swagger::Docs::Generator do
       end
     end
     context "resource file" do
-      let(:resource) { File.read(FILE_RESOURCE)}
+      let(:resource) { FILE_RESOURCE.read }
       let(:response) { JSON.parse(resource) }
       let(:first) { response["apis"].first }
       let(:operations) { first["operations"] }
@@ -79,7 +81,7 @@ describe Swagger::Docs::Generator do
 
   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"}
+      DEFAULT_VER => {: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)
@@ -89,48 +91,63 @@ describe Swagger::Docs::Generator do
 
     context "test suite initialization" do
       it "the resources file does not exist" do
-        expect(File.exists?(FILE_RESOURCES)).to be_false
+        expect(FILE_RESOURCES).to_not exist
       end
       it "the resource file does not exist" do
-        expect(File.exists?(FILE_RESOURCE)).to be_false
+        expect(FILE_RESOURCE).to_not exist
       end
     end
 
     describe "#write_docs" do
+      context "no apis registered" do
+        before(:each) do 
+          Swagger::Docs::Config.register_apis({})
+        end
+        it "generates using default config" do
+          results = generate({})
+          expect(results[DEFAULT_VER][:processed].count).to eq 1
+        end
+      end
       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_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
+        expect(file_to_delete).to exist
+        config[DEFAULT_VER][:clean_directory] = true
         generate(config)
-        expect(File.exists?(file_to_delete)).to be_false
+        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 = TMP_DIR+"api/v1/keep_me"
         File.open(file_to_keep, 'w') {|f| f.write("{}") }
-        config["1.0"][:clean_directory] = true
+        config[DEFAULT_VER][:clean_directory] = true
         generate(config)
-        expect(File.exists?(file_to_keep)).to be_true
+        expect(file_to_keep).to exist
       end
       it "writes the resources file" do
-        expect(File.exists?(FILE_RESOURCES)).to be_true
+        expect(FILE_RESOURCES).to exist
       end
       it "writes the resource file" do
-        expect(File.exists?(FILE_RESOURCE)).to be_true
+        expect(FILE_RESOURCE).to exist
       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
+        expect(results[DEFAULT_VER][:processed].count).to eq 1
+        expect(results[DEFAULT_VER][:skipped].count).to eq 1
+      end
+      it "writes pretty json files when set" do
+        config[DEFAULT_VER][:formatting] = :pretty
+        generate(config)
+        resources = File.read FILE_RESOURCES
+        expect(resources.scan(/\n/).length).to be > 1
       end
       context "resources files" do
-        let(:resources) { File.read(FILE_RESOURCES)}
+        let(:resources) { FILE_RESOURCES.read }
         let(:response) { JSON.parse(resources) }
         it "writes version correctly" do
-          expect(response["apiVersion"]).to eq "1.0"
+          expect(response["apiVersion"]).to eq DEFAULT_VER
         end
         it "writes swaggerVersion correctly" do
           expect(response["swaggerVersion"]).to eq "1.2"
@@ -149,7 +166,7 @@ describe Swagger::Docs::Generator do
         end
       end
       context "resource file" do
-        let(:resource) { File.read(FILE_RESOURCE)}
+        let(:resource) { FILE_RESOURCE.read }
         let(:response) { JSON.parse(resource) }
         let(:first) { response["apis"].first }
         let(:operations) { first["operations"] }
@@ -157,7 +174,7 @@ describe Swagger::Docs::Generator do
         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"
+          expect(response["apiVersion"]).to eq DEFAULT_VER
         end
         it "writes swaggerVersion correctly" do
           expect(response["swaggerVersion"]).to eq "1.2"
@@ -174,9 +191,14 @@ describe Swagger::Docs::Generator do
         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
+          it "writes path correctly when api extension type is not set" do
             expect(first["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"
+          end
           it "writes summary correctly" do
             expect(operations.first["summary"]).to eq "Fetches all User items"
           end
@@ -218,9 +240,12 @@ describe Swagger::Docs::Generator do
             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
         end
       end
     end
   end
-end
+end

data/spec/spec_helper.rb

@@ -2,11 +2,14 @@ require "rails"
 require "swagger/docs"
 require "ostruct"
 require "json"
+require 'pathname'
 
-TMP_DIR = "/tmp/swagger-docs/"
-TMP_API_DIR = "/tmp/swagger-docs/api/v1/"
-FILE_RESOURCES = "#{TMP_API_DIR}api-docs.json"
-FILE_RESOURCE = "#{TMP_API_DIR}sample.json"
+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|

data/swagger-docs.gemspec

@@ -26,4 +26,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "rake"
   spec.add_development_dependency "rspec"
   spec.add_development_dependency "rails"
+  spec.add_development_dependency "appraisal"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: swagger-docs
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.1.0
 platform: ruby
 authors:
 - Rich Hollis
@@ -30,7 +30,7 @@ cert_chain:
   RYcsqDfanYBx7QcftOnbeQq7/Ep7Zx+W9+Ph3TiJLMLdAr7bLkgN1SjvrjTL5mQR
   FuQtYvE4LKiUQpG7vLTRB78dQBlSj9fnv2OM9w==
   -----END CERTIFICATE-----
-date: 2013-11-04 00:00:00.000000000 Z
+date: 2014-02-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -88,6 +88,20 @@ dependencies:
     - - '>='
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: appraisal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Generates json files for rails apps to use with swagger-ui
 email:
 - richhollis@gmail.com
@@ -96,6 +110,8 @@ extensions: []
 extra_rdoc_files: []
 files:
 - .gitignore
+- Appraisals
+- CHANGELOG.md
 - Gemfile
 - LICENSE.txt
 - README.md