rack-swagger 0.0.1 → 0.0.6

checksums.yaml

@@ -1,7 +1,15 @@
 ---
-SHA1:
-  metadata.gz: e0a554961939896019de44e6da60716992d34071
-  data.tar.gz: bfa3d5c455e0a6f564510df8a1449b4628b53c9c
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    MjQ5NjkwY2ZjMGE0NTgyMWY0Yzg1M2U2YWZlY2RiM2YzOTkwYTJiYQ==
+  data.tar.gz: !binary |-
+    OTJjMDg5ZThmODYxNmM5OTFkYTM3MTE0YjlmNDcwOTA5NzU3Zjc5ZA==
 SHA512:
-  metadata.gz: d955aacbacb08ae3ccc95cb2955da65561ef237fae1dfd247368d77804625a8042468b60684db2e0739e829b6ee418f96de1a975b6642aee135df10a7bac5fb1
-  data.tar.gz: 18afc96f61fd03427cec5a0ac5547843ce164b8b747edc57d63b834b8ebb95f24baa400314f0ea6546edb8b126c28214fd2edc5648e3a47594be194e4dbaf369
+  metadata.gz: !binary |-
+    MjAwZDA5MzIzODAyNmUyNmJmYWM1ZWI5ZDI2NTA2N2UwN2FhMzExZWE0Y2Fk
+    NmY1MTg4N2U0M2NhMzYyMWQ4MTkyMzZlM2EwMmQ3MzhhOWIxOGVmNTZjZTM0
+    NDkwNDk0MDkyNjZmNzIxZWE1OTYzZDExZmU3Y2ZiYWM4NWZiZGQ=
+  data.tar.gz: !binary |-
+    NGQ4M2ZiNGNjMTkwMWYxNzkyYTRhMzk1N2ZjNzFhODM1ODY5YWM2MmNhNjZh
+    NzkyYzAzOTZhOGYzNGY4YzI3ZDVlMGFjMzk1ZTg3ZDc3NGJmYmFiOGJiMjc1
+    ZGQ1MzVkN2E1MmU0ZjViMTJmZThlYWNjMjc3ZjQ1NDE5MzM2ZjA=

data/.gitignore

@@ -11,4 +11,4 @@
 *.so
 *.o
 *.a
-mkmf.log
+mkmf.log

data/README.md

@@ -20,7 +20,90 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+Set up a docs folder in your project. Place the root API doc there and call it
+"swagger.json". Place your resource API docs there as well. For example, if you
+have one resource called "pet", your docs folder will have two files:
+
+* swagger.json (the root API doc)
+* pet.json (the pet resource)
+
+In your config.ru, run Rack::Swagger.app(), passing in the path to your docs
+folder.
+
+```ruby
+run Rack::Swagger.app(File.expand_path("../docs/", __FILE__))
+```
+
+This will serve the swagger-ui front-end at **/docs/**, and your
+doc files at **/docs/api-docs/**. 
+
+Your resource definitions should look ike this:
+
+```json
+  {
+    "path": "/pet",
+    "description": "Operations about pets"
+  },
+```
+
+## Getting basePath right
+
+##### Using overwrite_base_path
+
+If you are seeing a lot of 404s or CORS-related errors in your docs, you may
+need to tweak the basePath.
+
+You always need to have the basePath point to the same hostname as your API. If
+you have multiple deploys of your application under different hostnames, and
+they share the same set of JSON files, you can use the overwrite_base_path
+option in Rack::Swagger.app() to vary this dynamically.
+
+For example, say you have an environment variable called MY_API_HOST, which
+contains the hostname of your app for a given deployment:
+
+```ruby
+  Rack::Swagger.app(
+    File.expand_path("../docs/", __FILE__),
+    overwrite_base_path: ENV["MY_API_HOST"]
+  )
+```
+
+##### Setting basePath manually
+
+If you're not using overwrite_base_path, rack-swagger will just use your
+basePath value from your JSON files. But just know that basePath will have
+different values depending on the file:
+
+* For the resource files, it should point to the API root path.
+* For the root file, it should point to the API root path, plus "/docs/api-docs".
+
+## Upgrading swagger-ui
+
+A distribution of swagger-ui is included with rack-swagger. For developers who
+want to upgrade this distribution, there is a Rake task which pulls down the
+latest version and applies some changes to it. To use, run:
+
+```
+rake swagger_ui
+```
+
+If someone downloads the distribution without using the Rake task and you're
+trying to restore back to the original, remove the directory and version
+file before running the rake task:
+
+```
+rm -rf swagger-ui/
+rm swagger_ui_version.yml
+rake swagger_ui
+```
+
+Then check in the updated code.
+
+## Notes
+
+For an example of properly formatted Swagger 1.2 JSON files working together
+with [swagger-ui](https://github.com/wordnik/swagger-ui), see:
+[http://petstore.swagger.wordnik.com/](Pet Store Demo).
 
 ## Contributing
 
@@ -29,3 +112,4 @@ TODO: Write usage instructions here
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)
 5. Create a new Pull Request
+

data/Rakefile

@@ -1,2 +1,32 @@
 require "bundler/gem_tasks"
+require 'yaml'
+require 'httpclient'
+require 'json'
 
+task default: [:swagger_ui]
+
+desc "Update swagger-ui distribution files if they have changed."
+task swagger_ui: ["swagger-ui", :update_swagger_ui]
+
+directory "swagger-ui"
+
+task :update_swagger_ui do
+  client = HTTPClient.new
+  res = client.get('https://codeload.github.com/wordnik/swagger-ui/legacy.tar.gz/master', follow_redirect: true)
+  raise "Github API returned #{res.inspect}" if res.status != 200
+
+  # pull down swagger-ui mainline
+  cd "swagger-ui"
+  tar = res.content
+  File.open("master.tar.gz", "w+") { |f| f << tar }
+  sh("tar xvf master.tar.gz --include '*swagger-ui*/dist*' --strip-components 1")
+  cd ".."
+
+  # apply branding
+  puts `cat lib/rack/swagger/rentpath/rentpath.diff | patch -p1`
+  cp "lib/rack/swagger/rentpath/logo_small.png", "swagger-ui/dist/images/logo_small.png"
+
+  # replace petstore with real docs
+  index_page = File.read("swagger-ui/dist/index.html")
+  File.open("swagger-ui/dist/index.html", "w+") { |f| f << index_page.gsub("http://petstore.swagger.wordnik.com/api/api-docs", "api-docs") }
+end

data/lib/rack/swagger.rb

@@ -1,7 +1,41 @@
+require "rack/swagger/server_helpers"
+require "rack/swagger/asset_server"
+require "rack/swagger/index_page_server"
+require "rack/swagger/json_server"
+
+require "rack/swagger/sinatra_helpers"
 require "rack/swagger/version"
 
 module Rack
   module Swagger
-    # Your code goes here...
+    # Rack app for serving the swagger-ui front-end and your JSON-formatted
+    # Swagger doc files.
+    #
+    # Description:
+    #   The app will serve the swagger-ui front-end at /docs/, and redirect
+    #   requests for /docs to /docs/. It will serve the root Swagger doc
+    #   file at /docs/api-docs, and resource files in a subpath of /docs/api-docs,
+    #   such as /docs/api-docs/pet for the "pet" resource. This mimics the way
+    #   the Pet Store demo is set up.
+    #
+    #   See: http://petstore.swagger.wordnik.com/
+    #
+    # Parameters:
+    #   docs_dir: a String containing the path to the directory with your root
+    #   Swagger JSON doc file (called swagger.json) and all resource-specific
+    #   doc files (for example, pet.json for the "pet" resource).
+    #
+    # Usage:
+    #   In your config.ru, add:
+    #
+    #   run Rack::Swagger.app(File.expand_path("../docs/", __FILE__))
+    #
+    def self.app(docs_dir, opts={})
+      Rack::Cascade.new([
+        JsonServer.new(docs_dir, opts),
+        IndexPageServer.new,
+        AssetServer.new
+      ])
+    end
   end
 end

data/lib/rack/swagger/asset_server.rb

@@ -0,0 +1,22 @@
+module Rack
+  module Swagger
+    class AssetServer
+      include ServerHelpers
+
+      def initialize
+        dist_path = swagger_dist_path
+
+        @app = Rack::Builder.new do
+          map "/docs" do
+            run Rack::Directory.new(dist_path)
+          end
+        end
+      end
+
+      def call(env)
+        @app.call(env)
+      end
+    end
+  end
+end
+

data/lib/rack/swagger/index_page_server.rb

@@ -0,0 +1,32 @@
+module Rack
+  module Swagger
+    class IndexPageServer
+      include ServerHelpers
+
+      def call(env)
+        case env['PATH_INFO']
+        when "/docs/"
+          query = Rack::Utils.parse_nested_query(env["QUERY_STRING"])
+
+          if query["url"] == "api-docs"
+            display_file_or_404(:html, swagger_index_html_path)
+
+          else
+            res = Rack::Response.new
+            res.redirect("?url=" + "api-docs")
+            res.finish
+          end
+
+        when "/docs"
+          res = Rack::Response.new
+          res.redirect("docs/?url=" + "api-docs")
+          res.finish
+
+        else
+          [404, {}, ["Not found"]]
+        end
+      end
+    end
+  end
+end
+

data/lib/rack/swagger/json_server.rb

@@ -0,0 +1,30 @@
+module Rack
+  module Swagger
+    class JsonServer
+      include ServerHelpers
+
+      RESOURCE_DOC_JSON_MATCHER = /^\/docs\/api-docs\/(.+)\/?/
+      ROOT_DOC_JSON_MATCHER     = /^\/docs\/api-docs\/?/
+
+      def initialize(docs_dir, opts)
+        @docs_dir = docs_dir
+        @opts = opts
+      end
+
+      def call(env)
+        case env['PATH_INFO']
+        when RESOURCE_DOC_JSON_MATCHER
+          resource_doc = $1
+          display_file_or_404(:json, "#{@docs_dir}/#{resource_doc}.json", :resource)
+
+        when ROOT_DOC_JSON_MATCHER
+          display_file_or_404(:json, "#{@docs_dir}/swagger.json", :root)
+
+        else
+          [404, {}, ["Not found"]]
+        end
+      end
+    end
+  end
+end
+

data/lib/rack/swagger/rentpath/rentpath.diff

@@ -0,0 +1,47 @@
+diff --git a/swagger-ui/dist/css/screen.css b/swagger-ui/dist/css/screen.css
+index f214883..f5c779e 100644
+--- a/swagger-ui/dist/css/screen.css
++++ b/swagger-ui/dist/css/screen.css
+@@ -1158,7 +1158,7 @@
+   cursor: pointer;
+ }
+ .swagger-section #header {
+-  background-color: #89bf04;
++  background-color: #e7f0f7;
+   padding: 14px;
+ }
+ .swagger-section #header a#logo {
+@@ -1193,7 +1193,7 @@
+   padding: 6px 8px;
+   font-size: 0.9em;
+   color: white;
+-  background-color: #547f00;
++  background-color: #6090b0;
+   -moz-border-radius: 4px;
+   -webkit-border-radius: 4px;
+   -o-border-radius: 4px;
+diff --git a/swagger-ui/dist/images/logo_small.png b/swagger-ui/dist/images/logo_small.png
+index 5496a65..8891290 100644
+Binary files a/swagger-ui/dist/images/logo_small.png and b/swagger-ui/dist/images/logo_small.png differ
+diff --git a/swagger-ui/dist/index.html b/swagger-ui/dist/index.html
+index caf4ef0..1ccb8cc 100644
+--- a/swagger-ui/dist/index.html
++++ b/swagger-ui/dist/index.html
+@@ -1,7 +1,7 @@
+ <!DOCTYPE html>
+ <html>
+ <head>
+-  <title>Swagger UI</title>
++  <title>RentPath Mobile API Documentation</title>
+   <link href='//fonts.googleapis.com/css?family=Droid+Sans:400,700' rel='stylesheet' type='text/css'/>
+   <link href='css/reset.css' media='screen' rel='stylesheet' type='text/css'/>
+   <link href='css/screen.css' media='screen' rel='stylesheet' type='text/css'/>
+@@ -67,7 +67,7 @@
+ <body class="swagger-section">
+ <div id='header'>
+   <div class="swagger-ui-wrap">
+-    <a id="logo" href="http://swagger.wordnik.com">swagger</a>
++    <img src="images/logo_small.png"></img>
+     <form id='api_selector'>
+       <div class='input icon-btn'>
+         <img id="show-pet-store-icon" src="images/pet_store_api.png" title="Show Swagger Petstore Example Apis">

data/lib/rack/swagger/routes_to_models.rb

@@ -0,0 +1,111 @@
+require 'active_support/inflector/inflections'
+require 'active_support/inflections'
+require 'active_support/inflector/methods'
+require 'json'
+require 'pp'
+
+# A set of scripts for generating the "models" portion of the resource JSON
+# files.
+#
+# Usage:
+#    include Rack::Swagger::RoutesToModels
+#    models = generate_models(get_json("http://{URL}"))
+module Rack
+  module Swagger
+    module RoutesToModels
+      def get_json(url)
+        raw  = `curl "#{url}"`
+        json = JSON.parse raw
+      rescue
+        puts "#{__FILE__}:#{__LINE__}: URL not parsable."
+        {}
+      end
+
+      def traverse(gp='root', parent='root', obj, &blk)
+        case obj
+        when Hash
+          type = to_model_name(parent)
+          blk.call(gp, parent, type)
+          obj.each {|k,v| traverse(parent, k, v, &blk) }
+        when Array
+          type = to_model_name(parent, singularize: true)
+          blk.call(gp, parent, "[#{type}]")
+          obj.each {|v| traverse(parent, "#{type}", v, &blk) }
+        else
+          blk.call(gp, parent, "#{obj.class}")
+        end
+      end
+
+      def to_model_name(str, singularize: false)
+        str2 = ActiveSupport::Inflector.camelize(str)
+        str2 = ActiveSupport::Inflector.singularize(str2) if singularize
+        "Model_#{str2}"
+      end
+
+
+      def new_model(name)
+        {id: name, properties: {}}
+      end
+
+      def new_property(ruby_type)
+        case ruby_type
+        when "String"
+          {type: "string"}
+        when "Boolean"
+          {type: "boolean", format: "boolean"}
+        when "Float"
+          {type: "number", format: "float"}
+        when "Fixnum"
+          {type: "integer", format: "int64"}
+        when /\[(.+)\]/
+          {type: "array", items: new_property($1) }
+        else
+          { "$ref" => ruby_type.gsub(/^Model_/, "") }
+        end
+      end
+
+      def generate_models(json, root_name, debug=false)
+        models = {}
+
+        traverse('root', json) do |parent, obj_name, obj_type|
+          if ['FalseClass', 'TrueClass'].include? obj_type
+            obj_type = "Boolean"
+          end
+
+          if debug
+            puts sprintf("parent: %30s obj_name: %20s obj_type: %20s", parent, obj_name, obj_type.to_s[0...20])
+          end
+
+          if obj_type == "NilClass"
+            # skip
+
+          elsif parent.match(/^Model_/)
+            parent_wo_model = parent.gsub(/^Model_/, "")
+
+            unless models[parent_wo_model]
+              models[parent_wo_model] = new_model(parent_wo_model)
+            end
+
+            models[parent_wo_model][:properties][obj_name] = new_property(obj_type)
+          elsif !parent.match(/^Model_/) && !obj_name.match(/^Model_/)
+            c_parent = to_model_name(parent).gsub(/^Model_/, "")
+
+            unless models[c_parent]
+              models[c_parent] = new_model(c_parent)
+            end
+
+            models[c_parent][:properties][obj_name] = new_property(obj_type)
+          end
+        end
+
+        root = models["Root"]
+        models.delete("Root")
+        root[:properties].delete("root")
+        root[:id] = root_name
+
+        models[root_name] = root
+        models
+      end
+    end
+  end
+end