swagger_yard 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b6dfc1b55809fb818e9c2f1742a741ebbf72eb4d
-  data.tar.gz: cb8f8253cb95a55c04d6a9cd5b7488ae6d40b47c
+  metadata.gz: d61bc284164e43af94017cc989f2dc61ac5a98e2
+  data.tar.gz: b312468a3884e80013827ed6e82b5b00fe3539cf
 SHA512:
-  metadata.gz: b2c1e0eb8a9461f39d3161f62592c8cdf817f0c1fa9a8d3b9fc8231a171ee30246eb84fb74be727ed1671fde7244d740d5e4b774e5f5d0334c913e15270b7182
-  data.tar.gz: d47a31030769ce82fb1a7cb5242899562c229ed023c3155f25be48fd5f91a9d8ab7f9c67587073d645a0958d9b3bec7dec2d23ca55b2cf5dcfcca2ce54d90c21
+  metadata.gz: efc555082f8433aecca02e2d811943b10e8487701b68632670fd6c8f82b052eb849127d14498c58513e6aece261e9d8ea1cf8ab5b5ea2b5ccc94404d8a585f70
+  data.tar.gz: 081c4133f4c53d1845b547229250c5296b60ccee71a46e1c9970a71fdfc941c76701ae8ea63c19ade023f905dd712f14402048f0be234b361d6154d609740a26

data/README.md

@@ -23,10 +23,12 @@ Install the gem with Bunder:
       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"
+
+      # where your swagger spec json will show up
+      # configure this to match SwaggerYard::Rails mount point
+      config.swagger_spec_base_path = "http://localhost:3000/swagger/api"
     end
 
     # register swagger tags with YARD
@@ -129,12 +131,31 @@ 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.
+We suggest using something like [swagger-ui_rails](https://github.com/3scale/swagger-ui_rails/tree/dev-2.1.3) for your UI needs inside of Rails.
+
+To generate JSON from your code on request, checkout the [swagger_yard-rails](https://github.com/tpitale/swagger_yard-rails) project. This provides an engine to parse and render the json required for use by swagger-ui_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_yard-rails](https://github.com/tpitale/swagger_yard-rails)
 * [Swagger-spec version 2.0](https://github.com/wordnik/swagger-spec/blob/master/versions/2.0.md)
+* [Yard](https://github.com/lsegal/yard)
+
+## Current Parsing "Tree" Structure ##
+
+ResourceListing
+|
+-> ApiDeclaration (controller)
+| |
+| -> ListingInfo (controller class)
+| -> Authorization (header/param for auth, also added to ResourceListing?)
+| -> Api(s) (controller action, by path)
+|   |
+|   -> Operation(s) (controller action with HTTP method)
+|     |
+|     -> Parameter(s) (action param)
+| 
+-> Model (model)
+  |
+  -> Properties (model attributes)

data/lib/swagger_yard.rb

@@ -11,6 +11,7 @@ require "swagger_yard/api_declaration"
 require "swagger_yard/model"
 require "swagger_yard/api"
 require "swagger_yard/listing_info"
+require "swagger_yard/swagger"
 
 module SwaggerYard
   class << self
@@ -44,10 +45,6 @@ module SwaggerYard
       ::YARD::Registry.all
     end
 
-    def yard_objects_from_resource(resource_name)
-      yard_objects_from_file(resource_to_file_path[resource_name])
-    end
-
     ##
     # Register some custom yard tags used by swagger-ui
     def register_custom_yard_tags!

data/lib/swagger_yard/api.rb

@@ -1,6 +1,6 @@
 module SwaggerYard
   class Api
-    attr_accessor :path, :description
+    attr_accessor :path, :description, :operations, :api_declaration
 
     def self.path_from_yard_object(yard_object)
       if tag = yard_object.tags.detect {|t| t.tag_name == "path"}
@@ -29,21 +29,16 @@ module SwaggerYard
       @operations << Operation.from_yard_object(yard_object, self)
     end
 
-    def to_h
-      {
-        "path"        => path,
-        "description" => description,
-        "operations"  => @operations.map(&:to_h)
-      }
-    end
-
     def model_names
       @operations.map(&:model_names).flatten.compact.uniq
-      # @parameters.select {|p| ref?(p['type'])}.map {|p| p['type']}.uniq
     end
 
     def ref?(data_type)
       @api_declaration.ref?(data_type)
     end
+
+    def operations_hash
+      Hash[@operations.map {|op| [op.http_method.downcase, op.to_h]}]
+    end
   end
-end
+end

data/lib/swagger_yard/api_declaration.rb

@@ -1,6 +1,6 @@
 module SwaggerYard
   class ApiDeclaration
-    attr_accessor :description, :resource_path
+    attr_accessor :description, :resource, :resource_path
     attr_reader :apis, :authorizations
 
     def initialize(resource_listing)
@@ -23,17 +23,18 @@ module SwaggerYard
 
     def add_yard_object(yard_object)
       case yard_object.type
-      when :class
+      when :class # controller
         add_listing_info(ListingInfo.new(yard_object))
         add_authorizations_to_resource_listing(yard_object)
-      when :method
+      when :method # actions
         add_api(yard_object)
       end
     end
 
     def add_listing_info(listing_info)
-      @description = listing_info.description
-      @resource_path = listing_info.resource_path
+      @description   = listing_info.description
+      @resource      = listing_info.resource
+      @resource_path = listing_info.resource_path # required for valid? but nothing else
 
       # we only have api_key auth, the value for now is always empty array
       @authorizations = Hash[listing_info.authorizations.uniq.map {|k| [k, []]}]
@@ -67,23 +68,13 @@ module SwaggerYard
       @resource_listing.models.map(&:id).include?(name)
     end
 
-    def to_h
-      {
-        "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
-      }
+    def apis_hash
+      Hash[apis.map {|path, api| [path, api.operations_hash]}]
     end
 
-    def listing_hash
-      {
-        "path"        => resource_path,
-        "description" => description
-      }
+    def to_tag
+      { "name"        => resource,
+        "description" => description }
     end
 
     private

data/lib/swagger_yard/authorization.rb

@@ -26,11 +26,9 @@ module SwaggerYard
     end
 
     def to_h
-      {
-        "type" => type,
-        "passAs" => @pass_as,
-        "keyname" => @key
-      }
+      { "type" => type,
+        "name" => @key,
+        "in"   => @pass_as }
     end
   end
 end

data/lib/swagger_yard/configuration.rb

@@ -2,13 +2,17 @@ module SwaggerYard
   class Configuration
     attr_accessor :swagger_spec_base_path, :api_base_path, :api_path
     attr_accessor :swagger_version, :api_version
+    attr_accessor :title, :description
     attr_accessor :enable, :reload
+    attr_accessor :controller_path, :model_path
 
     def initialize
       self.swagger_version = "1.1"
       self.api_version = "0.1"
       self.enable = false
       self.reload = true
+      self.title = "Configure title with SwaggerYard.config.title"
+      self.description = "Configure description with SwaggerYard.config.description"
     end
   end
-end
+end

data/lib/swagger_yard/listing_info.rb

@@ -1,10 +1,14 @@
 module SwaggerYard
   class ListingInfo
-    attr_reader :description, :resource_path, :authorizations
+    attr_reader :description, :resource, :resource_path, :authorizations
 
     def initialize(yard_object)
       @description = yard_object.docstring
 
+      if tag = yard_object.tags.detect {|t| t.tag_name == "resource"}
+        @resource = tag.text
+      end
+
       if tag = yard_object.tags.detect {|t| t.tag_name == "resource_path"}
         @resource_path = tag.text.downcase
       end

data/lib/swagger_yard/model.rb

@@ -57,13 +57,10 @@ module SwaggerYard
     end
 
     def to_h
-      raise "Model is missing @model tag" if id.nil?
-
-      {
-        "id" => id,
-        "properties" => Hash[@properties.map {|property| [property.name, property.to_h]}],
-        "required" => @properties.select(&:required?).map(&:name)
-      }
+      {}.tap do |h|
+        h["properties"] = Hash[@properties.map {|p| [p.name, p.to_h]}]
+        h["required"] = @properties.select(&:required?).map(&:name) if @properties.detect(&:required?)
+      end
     end
   end
 end

data/lib/swagger_yard/operation.rb

@@ -1,6 +1,6 @@
 module SwaggerYard
   class Operation
-    attr_accessor :summary, :notes
+    attr_accessor :summary, :notes, :ruby_method
     attr_reader :path, :http_method, :error_messages, :response_type
     attr_reader :parameters, :model_names
 
@@ -9,6 +9,7 @@ module SwaggerYard
     # TODO: extract to operation builder?
     def self.from_yard_object(yard_object, api)
       new(api).tap do |operation|
+        operation.ruby_method = yard_object.name(false)
         yard_object.tags.each do |tag|
           case tag.tag_name
           when "path"
@@ -45,17 +46,37 @@ module SwaggerYard
     end
 
     def to_h
+      method      = http_method.downcase
+      description = notes || ""
+      params      = parameters.map(&:to_h)
+      responses   = { "default" => { "description" => summary || @api.description } }
+
+      if response_type
+        responses["default"]["schema"] = response_type.to_h
+      end
+
+      unless error_messages.empty?
+        error_messages.each do |err|
+          responses[err["code"].to_s] = {}.tap do |h|
+            h["description"] = err["message"]
+            h["schema"] = Type.from_type_list(Array(err["responseModel"])).to_h if err["responseModel"]
+          end
+        end
+      end
+
       {
-        "httpMethod"        => http_method,
-        "nickname"          => nickname,
-        "type"              => "void",
-        "produces"          => ["application/json", "application/xml"],
-        "parameters"        => parameters.map(&:to_h),
-        "summary"           => summary || @api.description,
-        "notes"             => notes,
-        "responseMessages"  => error_messages
+        "summary"     => summary || @api.description,
+        "tags"        => [@api.api_declaration.resource].compact,
+        "operationId" => "#{@api.api_declaration.resource}-#{ruby_method}",
+        "parameters"  => params,
+        "responses"   => responses,
       }.tap do |h|
-        h.merge!(response_type.to_h) if response_type
+        h["description"] = description unless description.to_s.empty?
+
+        authorizations = @api.api_declaration.authorizations
+        unless authorizations.empty?
+          h["security"] = authorizations.map {|k,v| { k => v} }
+        end
       end
     end
 

data/lib/swagger_yard/parameter.rb

@@ -55,14 +55,21 @@ module SwaggerYard
     end
 
     def to_h
-      {
-        "paramType"       => param_type,
-        "name"            => name,
-        "description"     => description,
-        "required"        => required,
-        "allowMultiple"   => !!allow_multiple,
-        "allowableValues" => allowable_values_hash 
-      }.merge(@type.to_h).reject {|k,v| v.nil?}
+      { "name"        => name,
+        "description" => description,
+        "required"    => required,
+        "in"          => param_type
+      }.tap do |h|
+        if !Array(allowable_values).empty?
+          h["enum"] = allowable_values
+        end
+        if h["in"] == "body"
+          h["schema"] = @type.to_h
+        else
+          h.update(@type.to_h)
+        end
+        h["collectionFormat"] = 'multi' if !Array(allow_multiple).empty? && h["items"]
+      end
     end
   end
-end
+end

data/lib/swagger_yard/property.rb

@@ -28,9 +28,9 @@ module SwaggerYard
     end
 
     def to_h
-      result = @type.to_h
-      result["description"] = description if description
-      result
+      @type.to_h.tap do |h|
+        h["description"] = description if description
+      end
     end
   end
 end

data/lib/swagger_yard/resource_listing.rb

@@ -1,8 +1,11 @@
 module SwaggerYard
   class ResourceListing
-    attr_reader :api_declarations, :resource_to_file_path
     attr_accessor :authorizations
 
+    def self.all
+      new(SwaggerYard.config.controller_path, SwaggerYard.config.model_path)
+    end
+
     def initialize(controller_path, model_path)
       @model_path = model_path
       @controller_path = controller_path
@@ -19,25 +22,33 @@ module SwaggerYard
       @controllers ||= parse_controllers
     end
 
-    def declaration_for(resource_name)
-      controllers[resource_name]
+    def to_h
+      { "paths"               => path_objects,
+        "definitions"         => model_objects,
+        "tags"                => tag_objects,
+        "securityDefinitions" => security_objects }
+    end
+
+    def path_objects
+      controllers.map(&:apis_hash).inject({}) do |h, api_hash|
+        h.merge api_hash
+      end
     end
 
-    def to_h
-      {
-        "apiVersion"      => SwaggerYard.config.api_version,
-        "swaggerVersion"  => SwaggerYard.config.swagger_version,
-        "basePath"        => SwaggerYard.config.swagger_spec_base_path,
-        "apis"            => list_api_declarations,
-        "authorizations"  => authorizations_hash
-      }
+    # Resources
+    def tag_objects
+      controllers.map(&:to_tag)
     end
 
-  private
-    def list_api_declarations
-      controllers.values.sort_by(&:resource_path).map(&:listing_hash)
+    def model_objects
+      Hash[models.map {|m| [m.id, m.to_h]}]
     end
 
+    def security_objects
+      Hash[authorizations.map {|auth| [auth.name, auth.to_h]}]
+    end
+
+    private
     def parse_models
       return [] unless @model_path
 
@@ -47,13 +58,11 @@ module SwaggerYard
     end
 
     def parse_controllers
-      return {} unless @controller_path
-
-      Hash[Dir[@controller_path].map do |file_path|
-        declaration = create_api_declaration(file_path)
+      return [] unless @controller_path
 
-        [declaration.resource_name, declaration] if declaration.valid?
-      end.compact]
+      Dir[@controller_path].map do |file_path|
+        create_api_declaration(file_path)
+      end.select(&:valid?)
     end
 
     def create_api_declaration(file_path)
@@ -61,11 +70,5 @@ module SwaggerYard
 
       ApiDeclaration.new(self).add_yard_objects(yard_objects)
     end
-
-    def authorizations_hash
-      Hash[
-        authorizations.map(&:name).zip(authorizations.map(&:to_h)) # ugh
-      ]
-    end
   end
 end

data/lib/swagger_yard/swagger.rb

@@ -0,0 +1,19 @@
+module SwaggerYard
+  class Info
+    def to_h
+      { "title"       => SwaggerYard.config.title,
+        "description" => SwaggerYard.config.description,
+        "version"     => SwaggerYard.config.api_version }
+    end
+  end
+
+  class Swagger
+    def to_h
+      { "swagger"  => "2.0",
+        "info"     => Info.new.to_h,
+        "host"     => URI(SwaggerYard.config.api_base_path).host,
+        "basePath" => URI(SwaggerYard.config.api_base_path).request_uri
+      }.merge(ResourceListing.all.to_h)
+    end
+  end
+end

data/lib/swagger_yard/type.rb

@@ -22,12 +22,32 @@ module SwaggerYard
 
     alias :array? :array
 
+    def json_type
+      type, format = name, nil
+      case name
+      when "float", "double"
+        type = "number"
+        format = name
+      when "date-time", "date", "time"
+        type = "string"
+        format = name
+      end
+      {}.tap do |h|
+        h["type"]   = type
+        h["format"] = format if format
+      end
+    end
+
     def to_h
-      type_tag = ref? ? "$ref" : "type"
+      type = if ref?
+        { "$ref" => "#/definitions/#{name}"}
+      else
+        json_type
+      end
       if array?
-        {"type"=>"array", "items"=> { type_tag => name }}
+        { "type" => "array", "items" => type }
       else
-        {"type"=>name}
+        type
       end
     end
   end

data/lib/swagger_yard/version.rb

@@ -1,3 +1,3 @@
 module SwaggerYard
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: swagger_yard
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - chtrinh (Chris Trinh)
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-10-15 00:00:00.000000000 Z
+date: 2015-10-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: yard
@@ -52,6 +52,34 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec-its
+  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'
+- !ruby/object:Gem::Dependency
+  name: apivore
+  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'
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
@@ -105,7 +133,6 @@ files:
 - MIT-LICENSE
 - README.md
 - Rakefile
-- config/routes.rb
 - lib/swagger_yard.rb
 - lib/swagger_yard/api.rb
 - lib/swagger_yard/api_declaration.rb
@@ -117,6 +144,7 @@ files:
 - lib/swagger_yard/parameter.rb
 - lib/swagger_yard/property.rb
 - lib/swagger_yard/resource_listing.rb
+- lib/swagger_yard/swagger.rb
 - lib/swagger_yard/type.rb
 - lib/swagger_yard/version.rb
 homepage: http://www.synctv.com

data/config/routes.rb

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