swagger_yard 0.0.5 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b7bdd63ad3c131a6f6d1a72c1c773a6b083dc13b
-  data.tar.gz: e1e5bba9bf16d673fc157c20204b42d0f36c016b
+  metadata.gz: b6dfc1b55809fb818e9c2f1742a741ebbf72eb4d
+  data.tar.gz: cb8f8253cb95a55c04d6a9cd5b7488ae6d40b47c
 SHA512:
-  metadata.gz: c2dfb163d06f32d74f097f87aebfffe1f4b6b905ee3475f88d825b05b05d6512127694723ffe273bf8d093ace6e0c5a04146b54e99e07f5f066176e4cd168e5e
-  data.tar.gz: b8e6e42710336cd98347c547959b2380d42e3b55d85d2abee6f4fb3a6bd08391bc2855a75eafc0d265bbdd82a68eeaeaee3f7e5aaa27d0a21dcb934720a1ef84
+  metadata.gz: b2c1e0eb8a9461f39d3161f62592c8cdf817f0c1fa9a8d3b9fc8231a171ee30246eb84fb74be727ed1671fde7244d740d5e4b774e5f5d0334c913e15270b7182
+  data.tar.gz: d47a31030769ce82fb1a7cb5242899562c229ed023c3155f25be48fd5f91a9d8ab7f9c67587073d645a0958d9b3bec7dec2d23ca55b2cf5dcfcca2ce54d90c21

data/README.md

@@ -1,15 +1,9 @@
-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
------------------
-  
+# SwaggerYard #
+
+SwaggerYard is a gem to convert extended YARD syntax comments into the swagger spec compliant json format.
+
+## Installation ##
+
 Put SwaggerYard in your Gemfile:
 
     gem 'swagger_yard'
@@ -19,95 +13,128 @@ Install the gem with Bunder:
     bundle install
 
 
-Getting Started
------------------
+## Getting Started ##
+
+### Place your configuration in a your rails initializers ###
 
-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
+      config.swagger_version = "1.2"
+      config.api_version = "1.0"
+      config.reload = Rails.env.development?
+
+      # where your swagger spec json will show up
+      config.swagger_spec_base_path = "http://localhost:3000/swagger/api"
+      # where your actual api is hosted from
+      config.api_base_path = "http://localhost:3000/api"
     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
+    # register swagger tags with YARD
+    SwaggerYard.register_custom_yard_tags!
+
+## Example Documentation ##
+
+### Here is an example of how to use SwaggerYard in your Controller ###
+
+**Note:** Model references should be Capitalized or CamelCased, basic types (integer, boolean, string, etc) should be lowercased everywhere.
+
+```ruby
+# @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 offset   [integer]               Used for pagination of response data (default: 25 items per response). Specifies the offset of the next block of data to receive.
+  # @parameter status   [array<string>]                 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 sort_descending    [boolean]     Reverse order of sort_order sorting, make it descending.
+  # @parameter begin_at_greater   [date]        Filters response to include only items with begin_at >= specified timestamp (e.g. begin_at_greater=2012-02-15T02:06:56Z).
+  # @parameter begin_at_less      [date]        Filters response to include only items with begin_at <= specified timestamp (e.g. begin_at_less=2012-02-15T02:06:56Z).
+  # @parameter end_at_greater     [date]        Filters response to include only items with end_at >= specified timestamp (e.g. end_at_greater=2012-02-15T02:06:56Z).
+  # @parameter end_at_less        [date]        Filters response to include only items with end_at <= specified timestamp (e.g. end_at_less=2012-02-15T02:06:56Z).
+  #
+  def index
+    ...
+  end
+
+  ##
+  # Returns an ownership for an account by id
+  # 
+  # @path [GET] /accounts/ownerships/{id}.{format_type}
+  # @response_type [Ownership]
+  # @error_message [EmptyOwnership] 404 Ownership not found
+  # @error_message 400 Invalid ID supplied
+  #
+  def show
+    ...
+  end
+end
+```
+
+### Here is an example of how to use SwaggerYard in your Model ###
+
+```ruby
+#
+# @model Pet
+#
+# @property id(required)    [integer]   the identifier for the pet
+# @property name  [Array<string>]    the names for the pet
+# @property age   [integer]   the age of the pet
+# @property relatives(required) [Array<Pet>] other Pets in its family
+#
+class Pet
+end
+```
+
+To then use your `Model` in your `Controller` documentation, add `@parameter`s:
+
+```ruby
+# @parameter [Pet] pet The pet object
+```
+
+## Authorization ##
+
+Currently, SwaggerYard only supports API Key auth descriptions. Start by adding `@authorization` to your `ApplicationController`.
+
+```ruby
+#
+# @authorization [api_key] header X-APPLICATION-API-KEY
+#
+class ApplicationController < ActionController::Base
+end
+```
+
+Then you can use these authorizations from your controller or actions in a controller. The name comes from either header or query plus the name of the key downcased/underscored.
+
+```ruby
+#
+# @authorize_with header_x_application_api_key
+#
+class PetController < ApplicationController
+end
+```
+
+## UI ##
+
+It is advisable to use something like [swagger-ui_rails](https://github.com/3scale/swagger-ui_rails/tree/dev-2.1.3) for your UI needs inside of Rails.
+
+## More Information ##
+
+* [Swagger-ui](https://github.com/wordnik/swagger-ui)
+* [swagger-ui_rails](https://github.com/3scale/swagger-ui_rails/tree/dev-2.1.3)
+* [Yard](https://github.com/lsegal/yard)
+* [Swagger-spec version 1.2](https://github.com/wordnik/swagger-spec/blob/master/versions/1.2.md)
+* [Swagger-spec version 2.0](https://github.com/wordnik/swagger-spec/blob/master/versions/2.0.md)

data/Rakefile

@@ -1,9 +1,6 @@
-#!/usr/bin/env rake
-begin
-  require 'bundler/setup'
-rescue LoadError
-  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
-end
+require 'bundler/setup'
+require 'bundler/gem_tasks'
+
 begin
   require 'rdoc/task'
 rescue LoadError
@@ -20,21 +17,8 @@ RDoc::Task.new(:rdoc) do |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
+require 'rspec/core/rake_task'
 
+RSpec::Core::RakeTask.new(:spec)
 
-task :default => :test
+task :default => :spec

data/lib/swagger_yard/api.rb

@@ -1,132 +1,49 @@
 module SwaggerYard
   class Api
-    attr_reader :nickname
-    attr_accessor :path, :parameters, :description, :http_method, :response_class, :summary, :notes, :error_responses
+    attr_accessor :path, :description
 
-    def initialize(yard_object)
-      @description = yard_object.docstring
-      @parameters  = []
-      
-      yard_object.tags.each do |tag|
-        value = tag.text
-
-        case tag.tag_name
-        when "path"
-          parse_path(value)
-        when "parameter"
-          @parameters << parse_parameter(value)
-        when "parameter_list"
-          @parameters << parse_parameter_list(value)
-        when "summary"
-          @summary = value
-        when "notes"
-          @notes = value.gsub("\n", "<br\>")
-        end
+    def self.path_from_yard_object(yard_object)
+      if tag = yard_object.tags.detect {|t| t.tag_name == "path"}
+        tag.text
+      else
+        nil
       end
+    end
+
+    def self.from_yard_object(yard_object, api_declaration)
+      path = path_from_yard_object(yard_object)
+      description = yard_object.docstring
 
-      @parameters.sort_by { |parameter| parameter["name"] }
-      @parameters << add_format_parameters
+      new(path, description, api_declaration)
     end
 
-    def nickname
-      @nickname ||= "#{http_method}".camelize
+    def initialize(path, description, api_declaration)
+      @api_declaration = api_declaration
+      @description = description
+      @path = path
+
+      @operations = []
     end
 
-    def operation 
-      {
-        "httpMethod"     => http_method,
-        "nickname"       => path[1..-1].gsub(/[^a-zA-Z\d:]/, '-').squeeze("-") + http_method.downcase,
-        "responseClass"  => response_class || "void",
-        "produces"       => ["application/json", "application/xml"],
-        "parameters"     => parameters,
-        "summary"        => summary || description,
-        "notes"          => notes,
-        "errorResponses" => error_responses
-      }
+    def add_operation(yard_object)
+      @operations << Operation.from_yard_object(yard_object, self)
     end
 
     def to_h
       {
         "path"        => path,
         "description" => description,
-        "operations"  => [operation],
+        "operations"  => @operations.map(&:to_h)
       }
     end
 
-    def valid?
-      path.present?
-    end
-
-  private
-    ##
-    # Example: [GET] /api/v2/ownerships.{format_type}
-    def parse_path(string)
-      @http_method, @path = string.match(/^\[(\w*)\]\s*(.*)$/).captures
-
-      path_params = @path.scan(/\{([^\}]+)\}/).flatten.reject { |value| value == "format_type" }
-      
-      path_params.each do |path_param|
-        @parameters << {
-          "paramType"     => "path",
-          "name"          => path_param,
-          "description"   => "Scope response to #{path_param}",
-          "dataType"      => "string",
-          "required"      => true,
-          "allowMultiple" => false
-        }
-      end
+    def model_names
+      @operations.map(&:model_names).flatten.compact.uniq
+      # @parameters.select {|p| ref?(p['type'])}.map {|p| p['type']}.uniq
     end
 
-    ##
-    # Example: [Array]     status            Filter by status. (e.g. status[]=1&status[]=2&status[]=3)
-    # Example: [Array]     status(required)  Filter by status. (e.g. status[]=1&status[]=2&status[]=3)
-    # Example: [Integer]   media[media_type_id]                          ID of the desired media type.
-    def parse_parameter(string)
-      data_type, name, required, description = string.match(/\A\[(\w*)\]\s*([\w\[\]]*)(\(required\))?\s*(.*)\Z/).captures
-      allow_multiple = name.gsub!("[]", "")
-
-      parameter = {
-        "paramType"     => "query",
-        "name"          => name,
-        "description"   => description,
-        "dataType"      => data_type.downcase,
-        "required"      => required.present?,
-        "allowMultiple" => allow_multiple.present?
-      }
-    end
-
-    ##
-    # Example: [String]    sort_order  Orders ownerships by fields. (e.g. sort_order=created_at)
-    #          [List]      id              
-    #          [List]      begin_at        
-    #          [List]      end_at          
-    #          [List]      created_at      
-    def parse_parameter_list(string)
-      data_type, name, required, description, set_string = string.match(/\A\[(\w*)\]\s*(\w*)(\(required\))?\s*(.*)\n([.\s\S]*)\Z/).captures
-      
-      list_values = set_string.split("[List]").map(&:strip).reject { |string| string.empty? }
-
-      parameter = {
-        "paramType"       => "query",
-        "name"            => name,
-        "description"     => description,
-        "dataType"        => data_type.downcase,
-        "required"        => required.present?,
-        "allowMultiple"   => false,
-        "allowableValues" => {"valueType" => 'LIST', "values" => list_values}
-      }
-    end
-
-    def add_format_parameters
-      @add_format_parameters ||= {
-        "paramType"       => "path",
-        "name"            => "format_type",
-        "description"     => "Response format either JSON or XML",
-        "dataType"        => "string",
-        "required"        => true,
-        "allowMultiple"   => false,
-        "allowableValues" => {"valueType" => "LIST", "values" => ["json", "xml"]}
-      }
+    def ref?(data_type)
+      @api_declaration.ref?(data_type)
     end
   end
 end

data/lib/swagger_yard/api_declaration.rb

@@ -1,42 +1,108 @@
 module SwaggerYard
   class ApiDeclaration
     attr_accessor :description, :resource_path
+    attr_reader :apis, :authorizations
+
+    def initialize(resource_listing)
+      @resource_listing = resource_listing
 
-    def initialize
       @apis   = {}
-      @models = []
+      @authorizations = {}
+    end
+
+    def valid?
+      !@resource_path.nil?
+    end
+
+    def add_yard_objects(yard_objects)
+      yard_objects.each do |yard_object|
+        add_yard_object(yard_object)
+      end
+      self
+    end
+
+    def add_yard_object(yard_object)
+      case yard_object.type
+      when :class
+        add_listing_info(ListingInfo.new(yard_object))
+        add_authorizations_to_resource_listing(yard_object)
+      when :method
+        add_api(yard_object)
+      end
     end
 
-    def add_listing_info(yard_object)
-      @description = yard_object.docstring if yard_object.docstring.present?
-      tag = yard_object.tags.find { |tag| tag.tag_name == "resource_path"}
-      @resource_path = tag.text.downcase if tag.present?
-      tag.present?
+    def add_listing_info(listing_info)
+      @description = listing_info.description
+      @resource_path = listing_info.resource_path
+
+      # we only have api_key auth, the value for now is always empty array
+      @authorizations = Hash[listing_info.authorizations.uniq.map {|k| [k, []]}]
     end
 
-    def add_api(api)
-      if @apis.keys.include?(api.path)
-        same_api_path = @apis[api.path]
-        same_api_path["operations"] << api.operation
-        @apis[api.path] = same_api_path
-      else
-        @apis[api.path] = api.to_h
-      end 
+    def add_api(yard_object)
+      path = Api.path_from_yard_object(yard_object)
+
+      return if path.nil?
+
+      api = (apis[path] ||= Api.from_yard_object(yard_object, self))
+      api.add_operation(yard_object)
+    end
+
+    # HACK, requires knowledge of resource_listing
+    def add_authorizations_to_resource_listing(yard_object)
+      yard_object.tags.select {|t| t.tag_name == "authorization"}.each do |t|
+        @resource_listing.authorizations << Authorization.from_yard_object(t)
+      end
     end
 
     def resource_name
       @resource_path
     end
 
+    def models
+      (api_models + property_models).uniq
+    end
+
+    def ref?(name)
+      @resource_listing.models.map(&:id).include?(name)
+    end
+
     def to_h
-      { 
-        "apiVersion"     => SwaggerYard.api_version,
-        "swaggerVersion" => SwaggerYard.swagger_version,
-        "basePath"       => SwaggerYard.api_base_path,
-        "resource_path"  => @resource_path,
-        "apis"           => @apis.values,
-        "models"         => @models
+      {
+        "apiVersion"     => SwaggerYard.config.api_version,
+        "swaggerVersion" => SwaggerYard.config.swagger_version,
+        "basePath"       => SwaggerYard.config.api_base_path,
+        "resourcePath"   => resource_path,
+        "apis"           => apis.values.map(&:to_h),
+        "models"         => Hash[models.map {|m| [m.id, m.to_h]}],
+        "authorizations"  => authorizations
       }
     end
+
+    def listing_hash
+      {
+        "path"        => resource_path,
+        "description" => description
+      }
+    end
+
+    private
+    def model_names_from_apis
+      apis.values.map(&:model_names).flatten.uniq
+    end
+
+    # models selected by the names of models referenced in APIs
+    def api_models
+      @resource_listing.models.select {|m| model_names_from_apis.include?(m.id)}
+    end
+
+    def model_names_from_model_properties
+      api_models.map{|model| model.recursive_properties_model_names(@resource_listing.models) }.flatten.uniq
+    end
+
+    # models selected by names used in properties in models used in APIs
+    def property_models
+      @resource_listing.models.select {|m| model_names_from_model_properties.include?(m.id)}
+    end
   end
-end
+end

data/lib/swagger_yard/authorization.rb

@@ -0,0 +1,36 @@
+module SwaggerYard
+  class Authorization
+    attr_reader :pass_as, :key
+    attr_writer :name
+
+    def self.from_yard_object(yard_object)
+      new(yard_object.types.first, yard_object.name, yard_object.text)
+    end
+
+    def initialize(type, pass_as, key)
+      @type, @pass_as, @key = type, pass_as, key
+    end
+
+    # the spec suggests most auth names are just the type of auth
+    def name
+      @name ||= [@pass_as, @key].join('_').downcase.gsub('-', '_')
+    end
+
+    def type
+      case @type
+      when "api_key"
+        "apiKey"
+      when "basic_auth"
+        "basicAuth"
+      end
+    end
+
+    def to_h
+      {
+        "type" => type,
+        "passAs" => @pass_as,
+        "keyname" => @key
+      }
+    end
+  end
+end

data/lib/swagger_yard/configuration.rb

@@ -0,0 +1,14 @@
+module SwaggerYard
+  class Configuration
+    attr_accessor :swagger_spec_base_path, :api_base_path, :api_path
+    attr_accessor :swagger_version, :api_version
+    attr_accessor :enable, :reload
+
+    def initialize
+      self.swagger_version = "1.1"
+      self.api_version = "0.1"
+      self.enable = false
+      self.reload = true
+    end
+  end
+end

data/lib/swagger_yard/listing_info.rb

@@ -0,0 +1,15 @@
+module SwaggerYard
+  class ListingInfo
+    attr_reader :description, :resource_path, :authorizations
+
+    def initialize(yard_object)
+      @description = yard_object.docstring
+
+      if tag = yard_object.tags.detect {|t| t.tag_name == "resource_path"}
+        @resource_path = tag.text.downcase
+      end
+
+      @authorizations = yard_object.tags.select {|t| t.tag_name == "authorize_with"}.map(&:text)
+    end
+  end
+end