swagger_yard 0.0.5

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: b7bdd63ad3c131a6f6d1a72c1c773a6b083dc13b
+  data.tar.gz: e1e5bba9bf16d673fc157c20204b42d0f36c016b
+SHA512:
+  metadata.gz: c2dfb163d06f32d74f097f87aebfffe1f4b6b905ee3475f88d825b05b05d6512127694723ffe273bf8d093ace6e0c5a04146b54e99e07f5f066176e4cd168e5e
+  data.tar.gz: b8e6e42710336cd98347c547959b2380d42e3b55d85d2abee6f4fb3a6bd08391bc2855a75eafc0d265bbdd82a68eeaeaee3f7e5aaa27d0a21dcb934720a1ef84

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2013 Chris Trinh
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,113 @@
+SwaggerYard
+==================
+
+The SwaggerYard gem is a Rails Engine designed to parse your Yardocs API controller.
+It'll create a Swagger-UI complaint JSON to be served out through where you mount SwaggerYard. 
+You can mount this to the Rails app serving the REST API or you could mount it as a separate Rails app.
+Parsing of the Yardocs happens during the server startup and the data will be subsequently cached to the Rails cache you have defined. 
+If your API is large expect a slow server start up time.
+
+Installation
+-----------------
+  
+Put SwaggerYard in your Gemfile:
+
+    gem 'swagger_yard'
+
+Install the gem with Bunder:
+
+    bundle install
+
+
+Getting Started
+-----------------
+
+Place your configuration in a your rails initializers
+    
+    # config/initializers/swagger_yard.rb
+    SwaggerYard.configure do |config|
+      config.swagger_version = "1.1"
+      config.api_version = "0.1"
+      config.doc_base_path = "http://swagger.example.com/doc"
+      config.api_base_path = "http://swagger.example.com/api"
+    end
+
+Mount your engine
+
+	# config/routes.rb
+	mount SwaggerYard::Engine, at: "/swagger"
+
+
+Example
+----------------
+
+Here is a example of how to use SwaggerYard
+
+
+    # @resource Account ownership
+    #
+    # @resource_path /accounts/ownerships
+    #
+    # This document describes the API for creating, reading, and deleting account ownerships.
+    #
+    class Accounts::OwnershipsController < ActionController::Base
+      ##
+      # Returns a list of ownerships associated with the account.
+      #
+      # @notes Status can be -1(Deleted), 0(Inactive), 1(Active), 2(Expired) and 3(Cancelled).
+      #
+      # @path [GET] /accounts/ownerships.{format_type}
+      #
+      # @parameter          [Integer]   offset            Used for pagination of response data (default: 25 items per response). Specifies the offset of the next block of data to receive.
+      # @parameter          [Array]     status            Filter by status. (e.g. status[]=1&status[]=2&status[]=3).
+      # @parameter_list     [String]    sort_order        Orders response by fields. (e.g. sort_order=created_at).
+      #                     [List]      id                
+      #                     [List]      begin_at          
+      #                     [List]      end_at            
+      #                     [List]      created_at        
+      # @parameter          [Boolean]   sort_descending   Reverse order of sort_order sorting, make it descending.
+      # @parameter          [Date]      begin_at_greater  Filters response to include only items with begin_at >= specified timestamp (e.g. begin_at_greater=2012-02-15T02:06:56Z).
+      # @parameter          [Date]      begin_at_less     Filters response to include only items with begin_at <= specified timestamp (e.g. begin_at_less=2012-02-15T02:06:56Z).
+      # @parameter          [Date]      end_at_greater    Filters response to include only items with end_at >= specified timestamp (e.g. end_at_greater=2012-02-15T02:06:56Z).
+      # @parameter          [Date]      end_at_less       Filters response to include only items with end_at <= specified timestamp (e.g. end_at_less=2012-02-15T02:06:56Z).
+      #
+      def index
+        ...
+      end
+    end
+
+
+![Web UI](https://raw.github.com/synctv/swagger_yard/master/example/web-ui.png)
+
+
+Generators
+----------------
+
+There are two generators that you can use 
+
+     rails g swagger_yard:ui
+     rails g swagger_yard:js
+
+They both copy over their respective files over to your Rails app to be customized. 
+See [rails engines overriding views](http://guides.rubyonrails.org/engines.html#overriding-views) for more info
+
+Copying over JS requires that ActionDispatch::Static middleware be used (by default it should in use).
+
+
+Notes
+-----------------
+
+By default SwaggerYard will use a slightly modify version of the swagger-ui. Changes to the JS code are indicated with "SwaggerYard changes" comments. The changes are mainly to support Rails way of supporting an array of parameters.
+
+
+More Information
+-----------------
+
+[Swagger-ui](https://github.com/wordnik/swagger-ui)
+[Yard](https://github.com/lsegal/yard)
+
+
+Author
+-----------------
+
+Chris Trinh

data/Rakefile

@@ -0,0 +1,40 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+begin
+  require 'rdoc/task'
+rescue LoadError
+  require 'rdoc/rdoc'
+  require 'rake/rdoctask'
+  RDoc::Task = Rake::RDocTask
+end
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'SwaggerYard'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+APP_RAKEFILE = File.expand_path("../test/dummy/Rakefile", __FILE__)
+load 'rails/tasks/engine.rake'
+
+
+
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+
+task :default => :test

data/app/controllers/swagger_yard/application_controller.rb

@@ -0,0 +1,4 @@
+module SwaggerYard
+  class ApplicationController < ActionController::Base
+  end
+end

data/app/controllers/swagger_yard/swagger_controller.rb

@@ -0,0 +1,21 @@
+module SwaggerYard
+  class SwaggerController < ApplicationController
+    layout false
+
+    def index
+      swagger_listing = SwaggerYard.get_listing
+      swagger_listing.merge!("basePath" => request.url) if swagger_listing["basePath"].blank?
+      render :json => swagger_listing
+    end
+
+    def show
+      swagger_api = SwaggerYard.get_api("/#{params[:resource]}")
+      swagger_api.merge!("basePath" => request.base_url + SwaggerYard.api_path) if swagger_api["basePath"].blank? 
+      render :json => swagger_api
+    end
+
+    def doc
+      render :doc
+    end
+  end
+end

data/app/views/swagger_yard/swagger/doc.html.erb

@@ -0,0 +1,80 @@
+<!DOCTYPE html>
+<html>
+<head>
+    <title>Swagger UI</title>
+    <link href='//fonts.googleapis.com/css?family=Droid+Sans:400,700' rel='stylesheet' type='text/css'/>
+    <link href='../swagger-ui/css/hightlight.default.css' media='screen' rel='stylesheet' type='text/css'/>
+    <link href='../swagger-ui/css/screen.css' media='screen' rel='stylesheet' type='text/css'/>
+    <script src='../swagger-ui/lib/jquery-1.8.0.min.js' type='text/javascript'></script>
+    <script src='../swagger-ui/lib/jquery.slideto.min.js' type='text/javascript'></script>
+    <script src='../swagger-ui/lib/jquery.wiggle.min.js' type='text/javascript'></script>
+    <script src='../swagger-ui/lib/jquery.ba-bbq.min.js' type='text/javascript'></script>
+    <script src='../swagger-ui/lib/handlebars-1.0.rc.1.js' type='text/javascript'></script>
+    <script src='../swagger-ui/lib/underscore-min.js' type='text/javascript'></script>
+    <script src='../swagger-ui/lib/backbone-min.js' type='text/javascript'></script>
+    <script src='../swagger-ui/lib/swagger.js' type='text/javascript'></script>
+    <script src='../swagger-ui/lib/MD5.js' type='text/javascript'></script>
+    <script src='../swagger-ui/lib/highlight.7.3.pack.js' type='text/javascript'></script>
+    <script src='../swagger-ui/swagger-ui.js' type='text/javascript'></script>
+
+    <script type="text/javascript">
+	$(function () {
+	    window.swaggerUi = new SwaggerUi({
+                discoveryUrl: location.protocol + "//" + location.host + "/swagger/api",
+                dom_id:"swagger-ui-container",
+                supportHeaderParams: true,
+                supportedSubmitMethods: ['get', 'post', 'put'],
+                onComplete: function(swaggerApi, swaggerUi){
+                	if(console) {
+                        console.log("Loaded SwaggerUI")
+                        console.log(swaggerApi);
+                        console.log(swaggerUi);
+                    }
+                  $('pre code').each(function(i, e) {hljs.highlightBlock(e)});
+                },
+                onFailure: function(data) {
+                	if(console) {
+                        console.log("Unable to Load SwaggerUI");
+                        console.log(data);
+                    }
+                },
+                docExpansion: "none"
+            });
+
+            window.swaggerUi.load();
+        });
+
+    </script>
+</head>
+
+<body>
+<div id='header'>
+    <div class="swagger-ui-wrap">
+        <a id="logo" href="http://swagger.wordnik.com">swagger</a>
+
+        <form id='api_selector'>
+            <div class='input icon-btn'>
+                <img id="show-pet-store-icon" src="../swagger-ui/images/pet_store_api.png" title="Show Swagger Petstore Example Apis">
+            </div>
+            <div class='input icon-btn'>
+                <img id="show-wordnik-dev-icon" src="../swagger-ui/images/wordnik_api.png" title="Show Wordnik Developer Apis">
+            </div>
+            <div class='input'><input placeholder="http://example.com/api" id="input_baseUrl" name="baseUrl"
+                                      type="text"/></div>
+            <div class='input'><input placeholder="api_key" id="input_apiKey" name="apiKey" type="text"/></div>
+            <div class='input'><a id="explore" href="#">Explore</a></div>
+        </form>
+    </div>
+</div>
+
+<div id="message-bar" class="swagger-ui-wrap">
+    &nbsp;
+</div>
+
+<div id="swagger-ui-container" class="swagger-ui-wrap">
+
+</div>
+
+</body>
+
+</html>

data/config/routes.rb

@@ -0,0 +1,6 @@
+SwaggerYard::Engine.routes.draw do
+   get '/doc', to: 'swagger#doc'
+
+   get '/api', to: 'swagger#index'
+   get '/api/*resource', to: 'swagger#show'
+end

data/lib/generators/swagger_yard/doc_generator.rb

@@ -0,0 +1,11 @@
+require 'rails/generators'
+module SwaggerYard
+  class DocGenerator < Rails::Generators::Base
+    source_root File.expand_path("../../../../app/views/swagger_yard/swagger", __FILE__)
+    desc "Add swagger-ui doc ERB file to app/views for customization"
+    
+    def generate_layout  
+      copy_file "doc.html.erb", "app/views/swagger_yard/swagger/doc.html.erb"
+    end
+  end
+end

data/lib/generators/swagger_yard/js_generator.rb

@@ -0,0 +1,13 @@
+require 'rails/generators'
+
+module SwaggerYard
+  class JsGenerator < Rails::Generators::Base
+    source_root File.expand_path("../../../../public/swagger-ui", __FILE__)
+    desc "Add swagger-ui js to /public for customization"
+    
+    def generate_layout  
+      copy_file "swagger-ui_org.js", "public/swagger-ui/swagger-ui.js"
+      directory "lib", "public/swagger-ui/lib"
+    end
+  end
+end

data/lib/swagger_yard.rb

@@ -0,0 +1,113 @@
+require "yard"
+require "swagger_yard/engine"
+require "swagger_yard/cache"
+require "swagger_yard/parser"
+
+module SwaggerYard
+  class << self
+    ##
+    # Configuration for Swagger Yard, use like:
+    #
+    #   SwaggerYard.configure do |config|
+    #     config.swagger_version = "1.1"
+    #     config.api_version = "0.1"
+    #     config.doc_base_path = "http://swagger.example.com/doc"
+    #     config.api_base_path = "http://swagger.example.com/api"
+    #   end
+    def configure
+      yield self
+    end
+
+    attr_accessor :doc_base_path, :api_base_path, :api_path
+    attr_writer :swagger_version, :api_version, :cache_store, :cache_prefix, :enable, :reload
+
+    def cache_store
+      @cache_store ||= Rails.cache
+    end
+    
+    def cache_prefix
+      @cache_prefix ||= "swagger_yard/"
+    end
+
+    def swagger_version
+      @swagger_version ||= "1.1"
+    end
+
+    def api_version
+      @api_version ||= "0.1"
+    end
+
+    def enable
+      @enable ||= false
+    end
+
+    def reload
+      @reload ||= false
+    end
+
+    def resource_to_file_path
+      @resource_to_file_path ||= {}
+    end
+
+    def parse_file(file_path)
+      ::YARD.parse(file_path)
+      yard_objects = ::YARD::Registry.all
+      ::YARD::Registry.clear
+      @parser.run(yard_objects)
+    end
+
+    def generate!(controller_path)
+      register_custom_yard_tags!
+      @controller_path = controller_path
+      cache.fetch("listing_index") { parse_controllers }
+    end
+
+    def get_api(resource_name)
+      if reload
+        parse_file(resource_to_file_path[resource_name]).to_h
+      else
+        cache.fetch(resource_name) { parse_file(resource_to_file_path[resource_name]).to_h }
+      end
+    end
+
+    def get_listing
+      if reload
+        parse_controllers
+      else
+        cache.fetch("listing_index") { parse_controllers }
+      end
+    end
+
+  private
+    ##
+    # Register some custom yard tags used by swagger-ui
+    def register_custom_yard_tags!
+      ::YARD::Tags::Library.define_tag("Api resource", :resource)
+      ::YARD::Tags::Library.define_tag("Resource path", :resource_path)
+      ::YARD::Tags::Library.define_tag("Api path", :path)
+      ::YARD::Tags::Library.define_tag("Parameter", :parameter)
+      ::YARD::Tags::Library.define_tag("Parameter list", :parameter_list)
+      ::YARD::Tags::Library.define_tag("Status code", :status_code)
+      ::YARD::Tags::Library.define_tag("Implementation notes", :notes)
+      ::YARD::Tags::Library.define_tag("Response class", :response_class)
+      ::YARD::Tags::Library.define_tag("Api Summary", :summary)
+    end
+
+    def cache
+      @cache ||= Cache.new(cache_store, cache_prefix)
+    end
+
+    def parse_controllers
+      @parser = Parser.new
+
+      Dir[@controller_path].each do |file|
+        if api_declaration = parse_file(file)
+          resource_to_file_path[api_declaration.resource_name] = file
+          cache[api_declaration.resource_name] = api_declaration.to_h
+        end
+      end
+
+      @parser.listing.to_h
+    end
+  end
+end