swagger_yard 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d61bc284164e43af94017cc989f2dc61ac5a98e2
-  data.tar.gz: b312468a3884e80013827ed6e82b5b00fe3539cf
+  metadata.gz: fe5802a169475d76a89dfdefa227b4e70f656851
+  data.tar.gz: 5a384463c1798693067ac7379093f28d1f194312
 SHA512:
-  metadata.gz: efc555082f8433aecca02e2d811943b10e8487701b68632670fd6c8f82b052eb849127d14498c58513e6aece261e9d8ea1cf8ab5b5ea2b5ccc94404d8a585f70
-  data.tar.gz: 081c4133f4c53d1845b547229250c5296b60ccee71a46e1c9970a71fdfc941c76701ae8ea63c19ade023f905dd712f14402048f0be234b361d6154d609740a26
+  metadata.gz: 0bad20c5172a080f1939eb511eac7b2c6930eb7bd3cf5f408a83100432f453bf9645c47bbbddc5bf35b98ab522d5f6d7e31f7a7277c19efd0607afa1ddfce309
+  data.tar.gz: c6d2040c142826db3ecd4e02fe4a9be55d09369addb94db8ed4b0081f0f87119142b7cc6a7ca7a2ddfd3638a224a26f34af3ee9233a1b9d7ee4db5cb3810edde

data/README.md

@@ -1,4 +1,4 @@
-# SwaggerYard #
+# SwaggerYard [![Build Status](https://travis-ci.org/tpitale/swagger_yard.svg?branch=master)](https://travis-ci.org/tpitale/swagger_yard) #
 
 SwaggerYard is a gem to convert extended YARD syntax comments into the swagger spec compliant json format.
 
@@ -15,30 +15,47 @@ Install the gem with Bunder:
 
 ## Getting Started ##
 
-### Place your configuration in a your rails initializers ###
+### Place configuration in a rails initializer ###
 
     # config/initializers/swagger_yard.rb
     SwaggerYard.configure do |config|
-      config.swagger_version = "1.2"
       config.api_version = "1.0"
       config.reload = Rails.env.development?
 
       # 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
-    SwaggerYard.register_custom_yard_tags!
+## SwaggerYard Usage ##
+
+### Types ###
+
+Types of things (parameters or responses of an operation, properties of a model)
+are indicated inside square-brackets (e.g., `[string]`) as part of a YARD tag.
+
+- Model references should be Capitalized or CamelCased by convention.
+- Basic types (integer, boolean, string, etc) should be lowercased.
+- An array of models or basic types is specified with `[array<...>]`.
+- An enum of allowed string values is specified with `[enum<one,two,three>]`.
+
+### Options ###
 
-## Example Documentation ##
+Parameter or property _options_ are expressed inside parenthesis immediately
+following the parameter or property name.
 
-### Here is an example of how to use SwaggerYard in your Controller ###
+Examples:
 
-**Note:** Model references should be Capitalized or CamelCased, basic types (integer, boolean, string, etc) should be lowercased everywhere.
+	# @parameter name(required) [string]  Name of the package
+	# @parameter package(body)  [Package] Package object
+
+Possible parameters include:
+
+- `required`: indicates a required parameter or property.
+- `multiple`: indicates a parameter may appear multiple times (usually in a
+  query string, e.g., `param=a&param=b&param=c`)
+- `body`/`query`/`path`/`formData`: Indicates where the parameter is located.
+
+### Example of using SwaggerYard in a Controller ###
 
 ```ruby
 # @resource Account ownership
@@ -51,17 +68,13 @@ 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).
+  # Status can be -1(Deleted), 0(Inactive), 1(Active), 2(Expired) and 3(Cancelled).
   #
-  # @path [GET] /accounts/ownerships.{format_type}
+  # @path [GET] /accounts/ownerships
   #
   # @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 status   [array<string>]         Filter by status. (e.g. status[]=1&status[]=2&status[]=3).
+  # @parameter sort_order [enum<id,begin_at,end_at,created_at>]  Orders response by fields. (e.g. sort_order=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).
@@ -75,7 +88,7 @@ class Accounts::OwnershipsController < ActionController::Base
   ##
   # Returns an ownership for an account by id
   # 
-  # @path [GET] /accounts/ownerships/{id}.{format_type}
+  # @path [GET] /accounts/ownerships/{id}
   # @response_type [Ownership]
   # @error_message [EmptyOwnership] 404 Ownership not found
   # @error_message 400 Invalid ID supplied
@@ -86,7 +99,7 @@ class Accounts::OwnershipsController < ActionController::Base
 end
 ```
 
-### Here is an example of how to use SwaggerYard in your Model ###
+### Example of using SwaggerYard in a Model ###
 
 ```ruby
 #
@@ -104,7 +117,7 @@ end
 To then use your `Model` in your `Controller` documentation, add `@parameter`s:
 
 ```ruby
-# @parameter [Pet] pet The pet object
+# @parameter pet(body) [Pet] The pet object
 ```
 
 ## Authorization ##
@@ -144,6 +157,7 @@ To generate JSON from your code on request, checkout the [swagger_yard-rails](ht
 
 ## Current Parsing "Tree" Structure ##
 
+```
 ResourceListing
 |
 -> ApiDeclaration (controller)
@@ -159,3 +173,25 @@ ResourceListing
 -> Model (model)
   |
   -> Properties (model attributes)
+```
+
+### Path Discovery Function ##
+
+SwaggerYard configuration allows setting of a "path discovery function" which
+will be called for controller action method documentation that have no `@path`
+tag. The function should return an array containing `["<method>", "<path>"]` if
+any can be determined.
+
+```ruby
+SwaggerYard.configure do |config|
+  config.path_discovery_function = ->(yard_obj) do
+    # code here to inspect the yard doc object
+	# and return a [method, path] for the api
+  end
+end
+```
+
+In [swagger_yard-rails][], this hook is used to set a function that inspects the
+Rails routing tables to reverse look up and compute paths.
+
+[swagger_yard-rails]: https://github.com/tpitale/swagger-yard_rails

data/lib/swagger_yard/api.rb

@@ -1,27 +1,30 @@
 module SwaggerYard
   class Api
-    attr_accessor :path, :description, :operations, :api_declaration
+    attr_accessor :path, :operations, :api_declaration
 
     def self.path_from_yard_object(yard_object)
       if tag = yard_object.tags.detect {|t| t.tag_name == "path"}
         tag.text
-      else
-        nil
+      elsif fn = SwaggerYard.config.path_discovery_function
+        begin
+          method, path = fn[yard_object]
+          yard_object.add_tag YARD::Tags::Tag.new("path", path, [method]) if path
+          path
+        rescue => e
+          YARD::Logger.instance.warn e.message
+          nil
+        end
       end
     end
 
     def self.from_yard_object(yard_object, api_declaration)
       path = path_from_yard_object(yard_object)
-      description = yard_object.docstring
-
-      new(path, description, api_declaration)
+      new(path, api_declaration)
     end
 
-    def initialize(path, description, api_declaration)
+    def initialize(path, api_declaration)
       @api_declaration = api_declaration
-      @description = description
       @path = path
-
       @operations = []
     end
 
@@ -29,14 +32,6 @@ module SwaggerYard
       @operations << Operation.from_yard_object(yard_object, self)
     end
 
-    def model_names
-      @operations.map(&:model_names).flatten.compact.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

data/lib/swagger_yard/api_declaration.rb

@@ -5,13 +5,13 @@ module SwaggerYard
 
     def initialize(resource_listing)
       @resource_listing = resource_listing
-
-      @apis   = {}
-      @authorizations = {}
+      @resource         = nil
+      @apis             = {}
+      @authorizations   = {}
     end
 
     def valid?
-      !@resource_path.nil?
+      !@resource.nil?
     end
 
     def add_yard_objects(yard_objects)
@@ -56,18 +56,6 @@ module SwaggerYard
       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 apis_hash
       Hash[apis.map {|path, api| [path, api.operations_hash]}]
     end
@@ -76,24 +64,5 @@ module SwaggerYard
       { "name"        => resource,
         "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

data/lib/swagger_yard/configuration.rb

@@ -1,18 +1,27 @@
 module SwaggerYard
   class Configuration
-    attr_accessor :swagger_spec_base_path, :api_base_path, :api_path
-    attr_accessor :swagger_version, :api_version
+    attr_accessor :api_version, :api_base_path
+    attr_accessor :swagger_version
     attr_accessor :title, :description
     attr_accessor :enable, :reload
     attr_accessor :controller_path, :model_path
+    attr_accessor :path_discovery_function
 
     def initialize
-      self.swagger_version = "1.1"
+      self.swagger_version = "2.0"
       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
+
+    def swagger_spec_base_path=(ignored)
+      warn "DEPRECATED: swagger_spec_base_path is no longer necessary."
+    end
+
+    def api_path=(ignored)
+      warn "DEPRECATED: api_path is no longer necessary."
+    end
   end
 end

data/lib/swagger_yard/model.rb

@@ -41,21 +41,6 @@ module SwaggerYard
       self
     end
 
-    def properties_model_names
-      @properties.map(&:model_name).compact
-    end
-
-    def recursive_properties_model_names(model_list)
-      properties_model_names + properties_model_names.map do |model_name|
-        child_model = model_from_model_list(model_list, model_name)
-        child_model.recursive_properties_model_names(model_list) if child_model
-      end.compact
-    end
-
-    def model_from_model_list(model_list, model_name)
-      model_list.find{|model| model.id == model_name}
-    end
-
     def to_h
       {}.tap do |h|
         h["properties"] = Hash[@properties.map {|p| [p.name, p.to_h]}]

data/lib/swagger_yard/operation.rb

@@ -1,55 +1,50 @@
 module SwaggerYard
   class Operation
-    attr_accessor :summary, :notes, :ruby_method
-    attr_reader :path, :http_method, :error_messages, :response_type
+    attr_accessor :description, :ruby_method
+    attr_writer :summary
+    attr_reader :path, :http_method, :error_messages, :response_type, :response_desc
     attr_reader :parameters, :model_names
 
-    PARAMETER_LIST_REGEX = /\A\[(\w*)\]\s*(\w*)(\(required\))?\s*(.*)\n([.\s\S]*)\Z/
-
     # 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)
+        operation.description = yard_object.docstring
         yard_object.tags.each do |tag|
           case tag.tag_name
           when "path"
             operation.add_path_params_and_method(tag)
           when "parameter"
             operation.add_parameter(tag)
-          when "parameter_list"
-            operation.add_parameter_list(tag)
           when "response_type"
-            operation.add_response_type(Type.from_type_list(tag.types))
+            operation.add_response_type(Type.from_type_list(tag.types), tag.text)
           when "error_message"
             operation.add_error_message(tag)
           when "summary"
             operation.summary = tag.text
-          when "notes"
-            operation.notes = tag.text.gsub("\n", "<br\>")
           end
         end
 
         operation.sort_parameters
-        operation.append_format_parameter
       end
     end
 
     def initialize(api)
-      @api = api
-      @parameters = []
-      @model_names = []
+      @api            = api
+      @summary        = nil
+      @description    = ""
+      @parameters     = []
+      @model_names    = []
       @error_messages = []
     end
 
-    def nickname
-      @path[1..-1].gsub(/[^a-zA-Z\d:]/, '-').squeeze("-") + http_method.downcase
+    def summary
+      @summary || description.split("\n\n").first
     end
 
     def to_h
-      method      = http_method.downcase
-      description = notes || ""
       params      = parameters.map(&:to_h)
-      responses   = { "default" => { "description" => summary || @api.description } }
+      responses   = { "default" => { "description" => response_desc || summary } }
 
       if response_type
         responses["default"]["schema"] = response_type.to_h
@@ -65,13 +60,13 @@ module SwaggerYard
       end
 
       {
-        "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["description"] = description unless description.to_s.empty?
+        h["description"] = description unless description.empty?
+        h["summary"]     = summary unless summary.empty?
 
         authorizations = @api.api_declaration.authorizations
         unless authorizations.empty?
@@ -81,8 +76,8 @@ module SwaggerYard
     end
 
     ##
-    # Example: [GET] /api/v2/ownerships.{format_type}
-    # Example: [PUT] /api/v1/accounts/{account_id}.{format_type}
+    # Example: [GET] /api/v2/ownerships
+    # Example: [PUT] /api/v1/accounts/{account_id}
     def add_path_params_and_method(tag)
       @path = tag.text
       @http_method = tag.types.first
@@ -102,27 +97,12 @@ module SwaggerYard
     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 add_parameter_list(tag)
-      # TODO: switch to using Parameter.from_yard_tag
-      data_type, name, required, description, list_string = parse_parameter_list(tag)
-      allowable_values = parse_list_values(list_string)
-
-      @parameters << Parameter.new(name, Type.new(data_type.downcase), description, {
-        required: !!required,
-        param_type: "query",
-        allow_multiple: false,
-        allowable_values: allowable_values
-      })
-    end
-
-    def add_response_type(type)
+    # Example:
+    # @response_type [Ownership] the requested ownership
+    def add_response_type(type, desc)
       model_names << type.model_name
       @response_type = type
+      @response_desc = desc
     end
 
     def add_error_message(tag)
@@ -137,34 +117,9 @@ module SwaggerYard
       @parameters.sort_by! {|p| p.name}
     end
 
-    def append_format_parameter
-      @parameters << format_parameter
-    end
-
-    def ref?(data_type)
-      @api.ref?(data_type)
-    end
-
     private
     def parse_path_params(path)
-      path.scan(/\{([^\}]+)\}/).flatten.reject { |value| value == "format_type" }
-    end
-
-    def parse_parameter_list(tag)
-      tag.text.match(PARAMETER_LIST_REGEX).captures
-    end
-
-    def parse_list_values(list_string)
-      list_string.split("[List]").map(&:strip).reject { |string| string.empty? }
-    end
-
-    def format_parameter
-      Parameter.new("format_type", Type.new("string"), "Response format either JSON or XML", {
-        required: true,
-        param_type: "path",
-        allow_multiple: false,
-        allowable_values: ["json", "xml"]
-      })
+      path.scan(/\{([^\}]+)\}/).flatten
     end
   end
 end

data/lib/swagger_yard/parameter.rb

@@ -1,7 +1,7 @@
 module SwaggerYard
   class Parameter
     attr_accessor :name, :description
-    attr_reader :param_type, :required, :allow_multiple, :allowable_values
+    attr_reader :param_type, :required, :allow_multiple
 
     def self.from_yard_tag(tag, operation)
       description = tag.text
@@ -38,20 +38,6 @@ module SwaggerYard
       @required = options[:required] || false
       @param_type = options[:param_type] || 'query'
       @allow_multiple = options[:allow_multiple] || false
-      @allowable_values = options[:allowable_values] || []
-    end
-
-    def type
-      @type.name
-    end
-
-    def allowable_values_hash
-      return nil if allowable_values.empty?
-
-      {
-        "valueType" => "LIST",
-        "values" => allowable_values
-      }
     end
 
     def to_h
@@ -60,9 +46,6 @@ module SwaggerYard
         "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

data/lib/swagger_yard/property.rb

@@ -23,10 +23,6 @@ module SwaggerYard
       @required
     end
 
-    def model_name
-      @type.model_name
-    end
-
     def to_h
       @type.to_h.tap do |h|
         h["description"] = description if description

data/lib/swagger_yard/resource_listing.rb

@@ -30,9 +30,7 @@ module SwaggerYard
     end
 
     def path_objects
-      controllers.map(&:apis_hash).inject({}) do |h, api_hash|
-        h.merge api_hash
-      end
+      controllers.map(&:apis_hash).reduce({}, :merge)
     end
 
     # Resources

data/lib/swagger_yard/type.rb

@@ -2,13 +2,20 @@ module SwaggerYard
   class Type
     def self.from_type_list(types)
       parts = types.first.split(/[<>]/)
-      new(parts.last, parts.grep(/array/i).any?)
+      args = [parts.last]
+      case parts.first
+      when /^array$/i
+        args << true
+      when /^enum$/i
+        args = [nil, false, parts.last.split(/[,|]/)]
+      end if parts.size > 1
+      new(*args)
     end
 
-    attr_reader :name, :array
+    attr_reader :name, :array, :enum
 
-    def initialize(name, array=false)
-      @name, @array = name, array
+    def initialize(name, array = false, enum = nil)
+      @name, @array, @enum = name, array, enum
     end
 
     # TODO: have this look at resource listing?
@@ -21,6 +28,7 @@ module SwaggerYard
     end
 
     alias :array? :array
+    alias :enum? :enum
 
     def json_type
       type, format = name, nil
@@ -41,6 +49,8 @@ module SwaggerYard
     def to_h
       type = if ref?
         { "$ref" => "#/definitions/#{name}"}
+      elsif enum?
+        { "type" => "string", "enum" => @enum }
       else
         json_type
       end

data/lib/swagger_yard/version.rb

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

data/lib/swagger_yard.rb

@@ -52,9 +52,7 @@ module SwaggerYard
       ::YARD::Tags::Library.define_tag("Resource path", :resource_path)
       ::YARD::Tags::Library.define_tag("Api path", :path, :with_types)
       ::YARD::Tags::Library.define_tag("Parameter", :parameter, :with_types_name_and_default)
-      ::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 type", :response_type, :with_types)
       ::YARD::Tags::Library.define_tag("Error response message", :error_message, :with_types_and_name)
       ::YARD::Tags::Library.define_tag("Api Summary", :summary)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: swagger_yard
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - chtrinh (Chris Trinh)
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-10-21 00:00:00.000000000 Z
+date: 2015-11-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: yard