spectacle 0.1.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: b42ae059b23d5ff986e540814af430c8caaa0626
+  data.tar.gz: aa149c1772cdfe1d28e949a1d2db6e660e77450c
+SHA512:
+  metadata.gz: 36053c1424daf39030a9ada1ebb67615153c5bc998f762119dd0719ba1e95a91f8ec5fda7d230d07a8c72029807a6311415c74b33e451f0d56961876f4bc7267
+  data.tar.gz: 08a660ac60c8932c97bdce2566e573b773f7f94a62481f3eeed7a78396ace18404b210a58b1a6eb84b356bf865ebe0a942231ba7d702c6923e3bf541a5f1ab18

data/.gitignore

@@ -0,0 +1,22 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+public
+bak
+node_modules
+app/views/*/*
+vendor/assets/*/*

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in spectacle.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Rich Hollis
+
+MIT License
+
+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,13 @@
+# Spectacle
+
+Generate beautiful static documentation for your Rails API from OpenAPI/Swagger 2.0 specifications.
+
+## 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'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +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/certs/gem-public_cert.pem

@@ -0,0 +1,21 @@
+-----BEGIN CERTIFICATE-----
+MIIDeDCCAmCgAwIBAgIBATANBgkqhkiG9w0BAQUFADBBMRMwEQYDVQQDDApyaWNo
+aG9sbGlzMRUwEwYKCZImiZPyLGQBGRYFZ21haWwxEzARBgoJkiaJk/IsZAEZFgNj
+b20wHhcNMTMxMDIyMTMwMzI3WhcNMTQxMDIyMTMwMzI3WjBBMRMwEQYDVQQDDApy
+aWNoaG9sbGlzMRUwEwYKCZImiZPyLGQBGRYFZ21haWwxEzARBgoJkiaJk/IsZAEZ
+FgNjb20wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDppQTU++yinAuC
+ydu87c/vDGTmE5Go9/zI48/T0kTco+JbUn4BPUaK0DWCEpZULvqwQAqVQm8JQnIU
+6Z3k1tAQbhtgbG2oWNIxyC7SyXMQw/ag5qoAhw6k3DFE+jGKrREzADFb7vG+nPYp
+4yinx27jCTIAv7/z2AVt6HoHOYh1s0HniJQWCebi7QgNXboMY8MpFxSwNkcFjl14
+KMSf9SX7iOyiwqgcJmN0fN4be8pH5j/EdinUL1rWlwldcUo2+6LChBswRPmtdaZv
+UyICuX5VfVJA0KrA/ihIMLaZVO5esFso+YrpP+QgbvhLwhn5e/sB5dr3a+y0+GJZ
+zPGtm60bAgMBAAGjezB5MAkGA1UdEwQCMAAwCwYDVR0PBAQDAgSwMB0GA1UdDgQW
+BBShIiKLL1E1JG++RUVAOSPO7rZV0TAfBgNVHREEGDAWgRRyaWNoaG9sbGlzQGdt
+YWlsLmNvbTAfBgNVHRIEGDAWgRRyaWNoaG9sbGlzQGdtYWlsLmNvbTANBgkqhkiG
+9w0BAQUFAAOCAQEAe4P1TzJlVhUn60Wx/431wNnuHZS9K4gSzmNr4zuZU6lP3rxx
+rMsSY1nJY1nTBqX9W62hO+KS14ncbZvNU59ao5YVXHDflEB3Yz20DP9E2Uws64Bx
+ify0Dwuq4VV2PiQbczuTGhGupzQpkMttWNZqVdjDbH5k8sGx3MumNX7YUJwUerhZ
+bTBme5soNyJzAeWBqCBPT9p98rC6vqhcBfAVF6RbERYL6MPyoBZWqGeuMR4H2X/v
+RYcsqDfanYBx7QcftOnbeQq7/Ep7Zx+W9+Ph3TiJLMLdAr7bLkgN1SjvrjTL5mQR
+FuQtYvE4LKiUQpG7vLTRB78dQBlSj9fnv2OM9w==
+-----END CERTIFICATE-----

data/config/routes.rb

@@ -0,0 +1,3 @@
+Spectacle::Engine.routes.draw do
+  root 'apidocs#show'
+end

data/lib/spectacle.rb

@@ -0,0 +1,5 @@
+require "spectacle/config"
+require "spectacle/engine"
+require "spectacle/dsl"
+require "spectacle/task"
+require "spectacle/version"

data/lib/spectacle/config.rb

@@ -0,0 +1,79 @@
+module Spectacle
+  class Config
+    class << self
+
+      def target_dir= value
+        @versions = value
+      end
+
+      def target_dir
+        @target_dir ||= 'public/apidocs'
+      end
+
+      def spec_file= value
+        @spec_file = value
+      end
+
+      def spec_file
+        @spec_file ||= 'public/swagger.json'
+      end
+
+
+      # @@base_api_controller = nil
+      #
+      # def base_api_controller
+      #   @@base_api_controller || ActionController::Base
+      # end
+      #
+      # def base_api_controllers
+      #   Array(base_api_controller)
+      # end
+      #
+      # def base_api_controller=(controller)
+      #   @@base_api_controller = controller
+      # end
+      #
+      # alias_method :base_api_controllers=, :base_api_controller=
+      #
+      # def base_applications
+      #   Array(base_application)
+      # end
+      #
+      # def base_application
+      #   Rails.application
+      # end
+      #
+      # def register_apis(versions)
+      #   base_api_controllers.each do |controller|
+      #     controller.send(:include, ImpotentMethods)
+      #   end
+      #   @versions = versions
+      # end
+      #
+      # def registered_apis
+      #   @versions ||= {}
+      # end
+      #
+      # def transform_path(path, api_version)
+      #   # This is only for overriding, so don't perform any path transformations by default.
+      #   path
+      # end
+      #
+      # def log_exception
+      #   yield
+      #   rescue => e
+      #     write_log(:error, e)
+      #     raise
+      # end
+      #
+      # def log_env_name
+      #   'SD_LOG_LEVEL'
+      # end
+      #
+      # def write_log(type, output)
+      #   $stderr.puts output if type == :error and ENV[log_env_name]=="1"
+      # end
+
+    end
+  end
+end

data/lib/spectacle/dsl.rb

@@ -0,0 +1,337 @@
+require 'open3'
+
+module Spectacle
+  class DSL
+
+    DEFAULT_CONFIG = {
+      spectacle_dir: 'node_modules/spectacle-docs' #,
+      # target_dir: 'public/apidocs',
+      # spec_path: 'public/swagger.json'#,
+      # :base_path: '/',
+      # :clean_directory: false,
+      # :formatting: :pretty
+    }
+
+    class << self
+
+      #
+      # Generate Spectacle static documentation
+      #
+      # @return success
+      #
+      def generate
+        res = run "-C -e #{Config.spec_file}"
+        p res
+        if res[2]
+          source_dir = "#{DEFAULT_CONFIG[:spectacle_dir]}/app"
+          build_dir = "#{DEFAULT_CONFIG[:spectacle_dir]}/public"
+          views_dir = './app/views/spectacle'
+          assets_dir = './vendor/assets'
+
+          FileUtils.mkdir_p views_dir
+          FileUtils.mkdir_p "#{assets_dir}/stylesheets"
+          FileUtils.mkdir_p "#{assets_dir}/javascripts"
+
+          FileUtils.cp "#{build_dir}/index.html",
+                       "#{views_dir}/_docs.html.erb"
+          FileUtils.cp Dir.glob("#{source_dir}/stylesheets/*"),
+                       "#{assets_dir}/stylesheets"
+          # FileUtils.copy "#{build_dir}/stylesheets/spectacle.css",
+          #              "#{assets_dir}/stylesheets/spectacle.css"
+          FileUtils.cp "#{build_dir}/javascripts/spectacle.js",
+                       "#{assets_dir}/javascripts/spectacle.js"
+        end
+        res
+      end
+
+      #
+      # Install Spectacle using `npm`
+      #
+      # @return success
+      #
+      def install
+        sh "npm install spectacle-docs"
+      end
+
+      #
+      # Run the Spectacle shell command
+      #
+      # @param args the command line arguments to pass to spectacle
+      #
+      # @return success
+      #
+      def run args
+        sh "cd #{DEFAULT_CONFIG[:spectacle_dir]} && node bin/cli #{args}"
+      end
+
+      #
+      # Identical to Open3.capture3, except that it rescues runtime errors
+      #
+      # @param env optional (as `Kernel.system')
+      # @param *cmd the command and its (auto-escaped) arguments
+      # @param opts optional a hash of options (as `Kernel.system')
+      #
+      # @return [stdout, stderr, success]
+      #
+      def sh(*cmd)
+        begin
+          stdout, stderr, status = Open3.capture3(*cmd)
+          [stdout, stderr, status.success?]
+        rescue
+          [$/, $/, nil]
+        end
+      end
+
+      # def set_real_methods
+      #   # replace impotent methods with live ones
+      #   Config.base_api_controllers.each do |controller|
+      #     controller.send(:include, Methods)
+      #   end
+      # end
+      #
+      # def write_docs(apis = nil)
+      #   results = generate_docs(apis)
+      #   results.each{|api_version, result| write_doc(result) }
+      # end
+      #
+      # def write_doc(result)
+      #   settings = result[:settings]
+      #   config = result[:config]
+      #   create_output_paths(settings[:api_file_path])
+      #   clean_output_paths(settings[:api_file_path]) if config[:clean_directory] || false
+      #   root = result[:root]
+      #   resources = root.delete 'resources'
+      #   root.merge!(config[:attributes] || {}) # merge custom user attributes like info
+      #   # write the api-docs file
+      #   write_to_file('#{settings[:api_file_path]}/#{config[:api_file_name]}', root, config)
+      #   # write the individual resource files
+      #   resources.each do |resource|
+      #     resource_file_path = resource.delete 'resourceFilePath'
+      #     write_to_file(File.join(settings[:api_file_path], '#{resource_file_path}.json'), resource, config)
+      #   end
+      #   result
+      # end
+      #
+      # def generate_docs(apis=nil)
+      #   apis ||= Config.registered_apis
+      #   results = {}
+      #   set_real_methods
+      #
+      #   apis[DEFAULT_VER] = DEFAULT_CONFIG if apis.empty?
+      #
+      #   apis.each do |api_version, config|
+      #     settings = get_settings(api_version, config)
+      #     config.reverse_merge!(DEFAULT_CONFIG)
+      #     results[api_version] = generate_doc(api_version, settings, config)
+      #     results[api_version][:settings] = settings
+      #     results[api_version][:config] = config
+      #   end
+      #   results
+      # end
+      #
+      # def generate_doc(api_version, settings, config)
+      #   root = {
+      #     'apiVersion': api_version,
+      #     'swaggerVersion': '1.2',
+      #     'basePath': settings[:base_path],
+      #     :apis: [],
+      #     :authorizations: settings[:authorizations]
+      #   }
+      #   results = {:processed: [], :skipped: []}
+      #   resources = []
+      #
+      #   get_route_paths(settings[:controller_base_path]).each do |path|
+      #     ret = process_path(path, root, config, settings)
+      #     results[ret[:action]] << ret
+      #     if ret[:action] == :processed
+      #       resources << generate_resource(ret[:path], ret[:apis], ret[:models], settings, root, config, ret[:klass].swagger_config)
+      #       debased_path = get_debased_path(ret[:path], settings[:controller_base_path])
+      #       resource_api = {
+      #         path: '/#{Config.transform_path(trim_leading_slash(debased_path), api_version)}.{format}',
+      #         description: ret[:klass].swagger_config[:description]
+      #       }
+      #       root[:apis] << resource_api
+      #     end
+      #   end
+      #   root['resources'] = resources
+      #   results[:root] = root
+      #   results
+      # end
+      #
+      # private
+      #
+      # def transform_spec_to_api_path(spec, controller_base_path, extension)
+      #   api_path = spec.to_s.dup
+      #   api_path.gsub!('(.:format)', extension ? '.#{extension}' : '')
+      #   api_path.gsub!(/:(\w+)/, '{\1}')
+      #   api_path.gsub!(controller_base_path, '')
+      #   '/' + trim_slashes(api_path)
+      # end
+      #
+      # def camelize_keys_deep!(h)
+      #   h.keys.each do |k|
+      #     ks    = k.to_s.camelize(:lower)
+      #     h[ks] = h.delete k
+      #     camelize_keys_deep! h[ks] if h[ks].kind_of? Hash
+      #     if h[ks].kind_of? Array
+      #       h[ks].each do |a|
+      #         next unless a.kind_of? Hash
+      #         camelize_keys_deep! a
+      #       end
+      #     end
+      #   end
+      # end
+      #
+      # def trim_leading_slash(str)
+      #   return str if !str
+      #   str.gsub(/\A\/+/, '')
+      # end
+      #
+      # def trim_trailing_slash(str)
+      #   return str if !str
+      #   str.gsub(/\/+\z/, '')
+      # end
+      #
+      # def trim_slashes(str)
+      #   trim_leading_slash(trim_trailing_slash(str))
+      # end
+      #
+      # def get_debased_path(path, controller_base_path)
+      #   path.gsub('#{controller_base_path}', '')
+      # end
+      #
+      # def process_path(path, root, config, settings)
+      #   return {action: :skipped, reason: :empty_path} if path.empty?
+      #   klass = Config.log_exception { '#{path.to_s.camelize}Controller'.constantize } rescue nil
+      #   return {action: :skipped, path: path, reason: :klass_not_present} if !klass
+      #   return {action: :skipped, path: path, reason: :not_swagger_resource} if !klass.methods.include?(:swagger_config) or !klass.swagger_config[:controller]
+      #   return {action: :skipped, path: path, reason: :not_kind_of_parent_controller} if config[:parent_controller] && !(klass < config[:parent_controller])
+      #   apis, models, defined_nicknames = [], {}, []
+      #   routes.select{|i| i.defaults[:controller] == path}.each do |route|
+      #     unless nickname_defined?(defined_nicknames, path, route) # only add once for each route once e.g. PATCH, PUT
+      #       ret = get_route_path_apis(path, route, klass, settings, config)
+      #       apis = apis + ret[:apis]
+      #       models.merge!(ret[:models])
+      #       defined_nicknames << ret[:nickname] if ret[:nickname].present?
+      #     end
+      #   end
+      #   {action: :processed, path: path, apis: apis, models: models, klass: klass}
+      # end
+      #
+      # def route_verbs(route)
+      #   if defined?(route.verb.source) then route.verb.source.to_s.delete('$'+'^').split('|') else [route.verb] end.collect{|verb| verb.downcase.to_sym}
+      # end
+      #
+      # def path_route_nickname(path, route)
+      #   action = route.defaults[:action]
+      #   '#{path.camelize}##{action}'
+      # end
+      #
+      # def nickname_defined?(defined_nicknames, path, route)
+      #   target_nickname = path_route_nickname(path, route)
+      #   defined_nicknames.each{|nickname| return true if nickname == target_nickname }
+      #   false
+      # end
+      #
+      # def generate_resource(path, apis, models, settings, root, config, swagger_config)
+      #   metadata = ApiDeclarationFileMetadata.new(
+      #     root['apiVersion'], path, root['basePath'],
+      #     settings[:controller_base_path],
+      #     camelize_model_properties: config.fetch(:camelize_model_properties, true),
+      #     swagger_version: root['swaggerVersion'],
+      #     authorizations: root[:authorizations],
+      #     resource_path: swagger_config[:resource_path]
+      #   )
+      #   declaration = ApiDeclarationFile.new(metadata, apis, models)
+      #   declaration.generate_resource
+      # end
+      #
+      # def routes
+      #   Config.base_applications.map{|app| app.routes.routes.to_a }.flatten
+      # end
+      #
+      # def get_route_path_apis(path, route, klass, settings, config)
+      #   models, apis = {}, []
+      #   action = route.defaults[:action]
+      #   verbs = route_verbs(route)
+      #   return {apis: apis, models: models, nickname: nil} if !operation = klass.swagger_actions[action.to_sym]
+      #   operation = Hash[operation.map {|k, v| [k.to_s.gsub('@','').to_sym, v.respond_to?(:deep_dup) ? v.deep_dup : v.dup] }] # rename :@instance hash keys
+      #   nickname = operation[:nickname] = path_route_nickname(path, route)
+      #
+      #   route_path = if defined?(route.path.spec) then route.path.spec else route.path end
+      #   api_path = transform_spec_to_api_path(route_path, settings[:controller_base_path], config[:api_extension_type])
+      #   operation[:parameters] = filter_path_params(api_path, operation[:parameters]) if operation[:parameters]
+      #   operations = verbs.collect{|verb|
+      #     op = operation.dup
+      #     op[:method] = verb
+      #     op
+      #   }
+      #   apis << {:path: api_path, :operations: operations}
+      #   models = get_klass_models(klass)
+      #
+      #   {apis: apis, models: models, nickname: nickname}
+      # end
+      #
+      # def get_klass_models(klass)
+      #   models = {}
+      #   # Add any declared models to the root of the resource.
+      #   klass.swagger_models.each do |model_name, model|
+      #     formatted_model = {
+      #       id: model[:id],
+      #       required: model[:required],
+      #       properties: model[:properties],
+      #     }
+      #     formatted_model[:description] = model[:description] if model[:description]
+      #     models[model[:id]] = formatted_model
+      #   end
+      #   models
+      # end
+      #
+      # def get_settings(api_version, config)
+      #   base_path = trim_trailing_slash(config[:base_path] || '')
+      #   controller_base_path = trim_leading_slash(config[:controller_base_path] || '')
+      #   base_path += '/#{controller_base_path}' unless controller_base_path.empty?
+      #   api_file_path = config[:api_file_path]
+      #   authorizations = config[:authorizations]
+      #   settings = {
+      #     base_path: base_path,
+      #     controller_base_path: controller_base_path,
+      #     api_file_path: api_file_path,
+      #     authorizations: authorizations
+      #   }.freeze
+      # end
+      #
+      # def get_route_paths(controller_base_path)
+      #   paths = routes.map{|i| '#{i.defaults[:controller]}' }
+      #   paths.uniq.select{|i| i.start_with?(controller_base_path)}
+      # end
+      #
+      # def create_output_paths(api_file_path)
+      #   FileUtils.mkdir_p(api_file_path) # recursively create out output path
+      # end
+      #
+      # def clean_output_paths(api_file_path)
+      #   Dir.foreach(api_file_path) do |f|
+      #     fn = File.join(api_file_path, f)
+      #     File.delete(fn) if !File.directory?(fn) and File.extname(fn) == '.json'
+      #   end
+      # end
+      #
+      # def write_to_file(path, structure, config={})
+      #   content = case config[:formatting]
+      #     when :pretty; JSON.pretty_generate structure
+      #     else;         structure.to_json
+      #   end
+      #   FileUtils.mkdir_p File.dirname(path)
+      #   File.open(path, 'w') { |file| file.write content }
+      # end
+      #
+      # def filter_path_params(path, params)
+      #   params.reject do |param|
+      #     param_as_variable = '{#{param[:name]}}'
+      #     param[:param_type] == :path && !path.include?(param_as_variable)
+      #   end
+      # end
+    end
+  end
+end