swagger_yard 0.4.4 → 1.0.0

data/lib/swagger_yard/operation.rb.~9b471577ebed4e4ba6ed266566355dbe5990787d~

@@ -0,0 +1,161 @@
+module SwaggerYard
+  class Operation
+    attr_accessor :description, :ruby_method
+    attr_writer :summary
+    attr_reader :path, :http_method, :error_messages, :response_type, :response_desc
+    attr_reader :parameters, :model_names
+
+    # 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"
+            tag = SwaggerYard.requires_type(tag)
+            operation.add_path_params_and_method(tag) if tag
+          when "parameter"
+            operation.add_parameter(tag)
+          when "response_type"
+            tag = SwaggerYard.requires_type(tag)
+            operation.add_response_type(Type.from_type_list(tag.types), tag.text) if tag
+          when "error_message"
+            operation.add_error_message(tag)
+          when "summary"
+            operation.summary = tag.text
+          end
+        end
+
+        operation.sort_parameters
+      end
+    end
+
+    def initialize(api)
+      @api            = api
+      @summary        = nil
+      @description    = ""
+      @parameters     = []
+      @model_names    = []
+      @error_messages = []
+    end
+
+    def summary
+      @summary || description.split("\n\n").first || ""
+    end
+
+    def to_h
+      params      = parameters.map(&:to_h)
+      responses   = { "default" => { "description" => response_desc || summary } }
+
+      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
+
+      api_decl = @api.api_declaration
+
+      {
+        "tags"        => [api_decl.resource].compact,
+        "operationId" => "#{api_decl.resource}-#{ruby_method}",
+        "parameters"  => params,
+        "responses"   => responses,
+      }.tap do |h|
+        h["description"] = description unless description.empty?
+        h["summary"]     = summary unless summary.empty?
+
+        authorizations = api_decl.authorizations
+        unless authorizations.empty?
+          h["security"] = authorizations.map {|k,v| { k => v} }
+        end
+
+        # Rails controller/action: if constantize/controller_path methods are
+        # unavailable or constant is not defined, catch exception and skip these
+        # attributes.
+        begin
+          h["x-controller"] = api_decl.class_name.constantize.controller_path.to_s
+          h["x-action"]     = ruby_method.to_s
+        rescue NameError, NoMethodError
+        end
+      end
+    end
+
+    ##
+    # Example: [GET] /api/v2/ownerships
+    # Example: [PUT] /api/v1/accounts/{account_id}
+    def add_path_params_and_method(tag)
+      if @path && @http_method
+        SwaggerYard.log.warn 'multiple path tags not supported: ' \
+          "ignored [#{tag.types.first}] #{tag.text}"
+        return
+      end
+
+      @path = tag.text
+      @http_method = tag.types.first
+
+      parse_path_params(tag.text).each do |name|
+        add_or_update_parameter Parameter.from_path_param(name)
+      end
+    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: [Array]     status(required, body)  Filter by status. (e.g. status[]=1&status[]=2&status[]=3)
+    # Example: [Integer]   media[media_type_id]                          ID of the desired media type.
+    def add_parameter(tag)
+      param = Parameter.from_yard_tag(tag, self)
+      add_or_update_parameter param if param
+    end
+
+    def add_or_update_parameter(parameter)
+      if existing = @parameters.detect {|param| param.name == parameter.name }
+        existing.description    = parameter.description unless parameter.from_path?
+        existing.param_type     = parameter.param_type if parameter.from_path?
+        existing.required     ||= parameter.required
+        existing.allow_multiple = parameter.allow_multiple
+      elsif parameter.param_type == 'body' && @parameters.detect {|param| param.param_type == 'body'}
+        SwaggerYard.log.warn 'multiple body parameters invalid: ' \
+          "ignored #{parameter.name} for #{@api.api_declaration.class_name}##{ruby_method}"
+      else
+        @parameters << parameter
+      end
+    end
+
+    ##
+    # 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)
+      tag = SwaggerYard.requires_name(tag)
+      return unless tag
+      @error_messages << {
+        "code" => Integer(tag.name),
+        "message" => tag.text,
+        "responseModel" => Array(tag.types).first
+      }.reject {|_,v| v.nil?}
+    end
+
+    def sort_parameters
+      @parameters.sort_by! {|p| p.name}
+    end
+
+    private
+    def parse_path_params(path)
+      path.scan(/\{([^\}]+)\}/).flatten
+    end
+  end
+end

data/lib/swagger_yard/parameter.rb

@@ -2,7 +2,7 @@ module SwaggerYard
   class Parameter
     attr_accessor :name, :type, :description, :param_type, :required, :allow_multiple
 
-    def self.from_yard_tag(tag, operation)
+    def self.from_yard_tag(tag)
       tag = SwaggerYard.requires_name_and_type(tag)
       return nil unless tag
 
@@ -13,8 +13,6 @@ module SwaggerYard
 
       options = {}
 
-      operation.model_names << type.name if type.ref?
-
       unless options_string.nil?
         options_string.split(',').map(&:strip).tap do |arr|
           options[:required] = !arr.delete('required').nil?
@@ -48,20 +46,5 @@ module SwaggerYard
     def from_path?
       @from_path
     end
-
-    def to_h
-      { "name"        => name,
-        "description" => description,
-        "required"    => required,
-        "in"          => param_type
-      }.tap do |h|
-        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

data/lib/swagger_yard/path_item.rb

@@ -0,0 +1,21 @@
+module SwaggerYard
+  class PathItem
+    attr_accessor :operations, :api_group
+
+    def initialize(api_group = nil)
+      @api_group = api_group
+      @operations = {}
+    end
+
+    def add_operation(yard_object)
+      operation = Operation.from_yard_object(yard_object, self)
+      @operations[operation.http_method.downcase] = operation
+    end
+
+    def +(other)
+      PathItem.new(api_group).tap do |pi|
+        pi.operations = operations.merge(other.operations)
+      end
+    end
+  end
+end

data/lib/swagger_yard/property.rb

@@ -3,7 +3,8 @@ module SwaggerYard
   # Holds the name and type for a single model property
   #
   class Property
-    attr_reader :name, :description
+    include Example
+    attr_reader :name, :description, :required, :type, :nullable
 
     def self.from_tag(tag)
       tag = SwaggerYard.requires_name_and_type(tag)
@@ -23,22 +24,8 @@ module SwaggerYard
       @type = Type.from_type_list(types)
     end
 
-    def required?
+     def required?
       @required
     end
-
-    def to_h
-      @type.to_h.tap do |h|
-        unless h['$ref']
-          h["description"] = description if description && !description.strip.empty?
-          if @nullable
-            h["x-nullable"] = true
-            if h["type"]
-              h["type"] = [h["type"], "null"]
-            end
-          end
-        end
-      end
-    end
   end
 end

data/lib/swagger_yard/{resource_listing.rb → specification.rb}

@@ -1,12 +1,9 @@
 module SwaggerYard
-  class ResourceListing
+  class Specification
     attr_accessor :authorizations
 
-    def self.all
-      new(SwaggerYard.config.controller_path, SwaggerYard.config.model_path)
-    end
-
-    def initialize(controller_path, model_path)
+    def initialize(controller_path = SwaggerYard.config.controller_path,
+                   model_path = SwaggerYard.config.model_path)
       @model_paths = [*model_path].compact
       @controller_paths = [*controller_path].compact
 
@@ -14,44 +11,34 @@ module SwaggerYard
       @authorizations = []
     end
 
-    def models
-      @models ||= parse_models
-    end
-
-    def controllers
-      @controllers ||= parse_controllers
-    end
-
-    def to_h
-      { "paths"               => path_objects,
-        "definitions"         => model_objects,
-        "tags"                => tag_objects,
-        "securityDefinitions" => security_objects }
-    end
-
     def path_objects
-      controllers.map(&:apis_hash).reduce({}, :merge).tap do |paths|
+      api_groups.map(&:paths).reduce(Paths.new({}), :merge).tap do |paths|
         warn_duplicate_operations(paths)
       end
     end
 
     # Resources
     def tag_objects
-      controllers.sort {|a,b| a.resource.upcase <=> b.resource.upcase}.map(&:to_tag)
+      api_groups.map(&:tag)
     end
 
     def model_objects
-      Hash[models.map {|m| [m.id, m.to_h]}]
+      Hash[models.map {|m| [m.id, m]}]
     end
 
     def security_objects
-      controllers # triggers controller parsing in case it did not happen before
-      SwaggerYard.config.security_definitions.merge(
-        Hash[authorizations.map {|auth| [auth.name, auth.to_h]}]
-      )
+      api_groups # triggers controller parsing in case it did not happen before
+      Hash[authorizations.map {|auth| [auth.id, auth]}]
     end
 
     private
+    def models
+      @models ||= parse_models
+    end
+
+    def api_groups
+      @api_groups ||= parse_controllers
+    end
 
     def parse_models
       @model_paths.map do |model_path|
@@ -70,7 +57,7 @@ module SwaggerYard
             obj.tags.select {|t| t.tag_name == "authorization"}.each do |t|
               @authorizations << Authorization.from_yard_object(t)
             end
-            ApiDeclaration.from_yard_object(obj)
+            ApiGroup.from_yard_object(obj)
           end
         end
       end.flatten.select(&:valid?)
@@ -78,13 +65,13 @@ module SwaggerYard
 
     def warn_duplicate_operations(paths)
       operation_ids = []
-      paths.each do |path,ops|
-        ops.each do |method,op|
-          if operation_ids.include?(op['operationId'])
-            SwaggerYard.log.warn("duplicate operation #{op['operationId']}")
+      paths.path_items.each do |path,pi|
+        pi.operations.each do |_, op|
+          if operation_ids.include?(op.operation_id)
+            SwaggerYard.log.warn("duplicate operation #{op.operation_id}")
             next
           end
-          operation_ids << op['operationId']
+          operation_ids << op.operation_id
         end
       end
     end

data/lib/swagger_yard/swagger.rb

@@ -10,15 +10,45 @@ module SwaggerYard
   end
 
   class Swagger
+    class << self; alias object_new new; end
+
+    def self.new(*args)
+      return OpenAPI.object_new(*args) if SwaggerYard.config.swagger_version.start_with?("3.0")
+      super
+    end
+
+    attr_reader :specification
+
+    def initialize(spec = Specification.new)
+      @specification = spec
+    end
+
     def to_h
+      metadata.merge(definitions).merge(model_definitions)
+    end
+
+    private
+    def model_path
+      Type::MODEL_PATH
+    end
+
+    def definitions
+      { "paths"               => paths(specification.path_objects),
+        "tags"                => tags(specification.tag_objects),
+        "securityDefinitions" => security_defs(specification.security_objects) }
+    end
+
+    def model_definitions
+      { "definitions" => models(specification.model_objects) }
+    end
+
+    def metadata
       {
         "swagger"  => "2.0",
         "info"     => Info.new.to_h
-      }.merge(uri_info).merge(ResourceListing.all.to_h)
+      }.merge(uri_info)
     end
 
-    private
-
     def uri_info
       uri = URI(SwaggerYard.config.api_base_path)
       host = uri.host
@@ -26,8 +56,146 @@ module SwaggerYard
 
       {
         'host' => host,
-        'basePath' => uri.request_uri
+        'basePath' => uri.request_uri,
+        'schemes' => [uri.scheme]
       }
     end
+
+    def paths(paths)
+      Hash[paths.path_items.map {|path,pi| [path, operations(pi.operations)] }]
+    end
+
+    def operations(ops)
+      expanded_ops = ops.map do |meth, op|
+
+        [meth, operation(op)]
+      end
+      Hash[expanded_ops]
+    end
+
+    def operation(op)
+      op_hash = {
+        "tags"        => op.tags,
+        "operationId" => op.operation_id,
+        "parameters"  => parameters(op.parameters),
+        "responses"   => responses(op.responses_by_status, op),
+      }
+
+      op_hash["description"] = op.description unless op.description.empty?
+      op_hash["summary"]     = op.summary unless op.summary.empty?
+
+      authorizations = op.api_group.authorizations
+      unless authorizations.empty?
+        op_hash["security"] = authorizations.map {|k,v| { k => v} }
+      end
+
+      op_hash.update(op.extended_attributes)
+    end
+
+    def parameters(params)
+      params.map do |param|
+        { "name"        => param.name,
+          "description" => param.description,
+          "required"    => param.required,
+          "in"          => param.param_type
+        }.tap do |h|
+          schema = param.type.schema_with(model_path: model_path)
+          if h["in"] == "body"
+            h["schema"] = schema
+          else
+            h.update(schema)
+          end
+          h["collectionFormat"] = 'multi' if !Array(param.allow_multiple).empty? && h["items"]
+        end
+      end
+    end
+
+    def responses(responses_by_status, op)
+      Hash[responses_by_status.map { |status, resp| [status, response(resp, op)] }]
+    end
+
+    def response(resp, op)
+      {}.tap do |h|
+        h['description'] = resp && resp.description || op.summary || ''
+        h['schema'] = resp.type.schema_with(model_path: model_path) if resp && resp.type
+        if resp && resp.example
+          h['examples'] = {
+            'application/json' => resp.example
+          }
+        end
+      end
+    end
+
+    def models(model_objects)
+      Hash[model_objects.map { |name, mod| [name, model(mod)] }]
+    end
+
+    def model(mod)
+      h = {}
+
+      if !mod.properties.empty? || mod.inherits.empty?
+        h["type"] = "object"
+        h["properties"] = Hash[mod.properties.map {|p| [p.name, property(p)]}]
+        h["required"] = mod.properties.select(&:required?).map(&:name) if mod.properties.detect(&:required?)
+      end
+
+      h["discriminator"] = mod.discriminator if mod.discriminator
+
+      # Polymorphism
+      unless mod.inherits.empty?
+        all_of = mod.inherits.map { |name| Type.new(name).schema_with(model_path: model_path) }
+        all_of << h unless h.empty?
+
+        if all_of.length == 1 && mod.description.empty?
+          h.update(all_of.first)
+        else
+          h = { "allOf" => all_of }
+        end
+      end
+
+      # Description
+      h["description"] = mod.description unless mod.description.empty?
+
+      h["example"] = mod.example if mod.example
+
+      h
+    end
+
+    def property(prop)
+      prop.type.schema_with(model_path: model_path).tap do |h|
+        unless h['$ref']
+          h["description"] = prop.description if prop.description && !prop.description.strip.empty?
+          if prop.nullable
+            h["x-nullable"] = true
+            if h["type"]
+              h["type"] = [h["type"], "null"]
+            end
+          end
+          h["example"] = prop.example if prop.example
+        end
+      end
+    end
+
+    def tags(tag_objects)
+      tag_objects.sort_by {|t| t.name.upcase }.map do |t|
+        { 'name' => t.name, 'description' => t.description }
+      end
+    end
+
+    def security_defs(security_objects)
+      config_defs = SwaggerYard.config.security_definitions
+      config_defs.merge(Hash[security_objects.map { |name, obj| [name, security(obj)] }])
+    end
+
+    def security(obj)
+      case obj.type
+      when /api_?key/i
+        { 'type' => 'apiKey', 'name' => obj.key, 'in' => obj.name }
+      else
+        { 'type' => 'basic' }
+      end.tap do |result|
+        result['description'] = obj.description if obj.description && !obj.description.empty?
+      end
+    end
   end
 end