swagger_yard 0.4.4 → 1.0.0

data/lib/swagger_yard/api_group.rb

@@ -0,0 +1,106 @@
+module SwaggerYard
+  class Tag < Struct.new(:name, :description)
+  end
+
+  class Paths
+    attr_reader :path_items
+
+    def initialize(path_items)
+      @path_items = path_items
+    end
+
+    def paths
+      path_items.keys
+    end
+
+    def merge(other)
+      merged_items = {}
+      (paths + other.paths).uniq.each do |path|
+        merged_items[path] = (path_items[path] || PathItem.new) + (other.path_items[path] || PathItem.new)
+      end
+      Paths.new(merged_items)
+    end
+  end
+
+  class ApiGroup
+    attr_accessor :description, :resource
+    attr_reader :path_items, :authorizations, :class_name
+
+    def self.from_yard_object(yard_object)
+      new.add_yard_object(yard_object)
+    end
+
+    def initialize
+      @resource       = nil
+      @path_items     = {}
+      @authorizations = {}
+    end
+
+    def valid?
+      !@resource.nil?
+    end
+
+    def paths
+      Paths.new(path_items)
+    end
+
+    def tag
+      @tag ||= Tag.new(resource, description)
+    end
+
+    def add_yard_object(yard_object)
+      case yard_object.type
+      when :class # controller
+        add_info(yard_object)
+        if valid?
+          yard_object.children.each do |child_object|
+            add_yard_object(child_object)
+          end
+        end
+      when :method # actions
+        add_path_item(yard_object)
+      end
+      self
+    end
+
+    def add_info(yard_object)
+      @description = yard_object.docstring
+      @class_name  = yard_object.path
+
+      if tag = yard_object.tags.detect {|t| t.tag_name == "resource"}
+        @resource = tag.text
+      end
+
+      # we only have api_key auth, the value for now is always empty array
+      @authorizations = Hash[yard_object.tags.
+                             select {|t| t.tag_name == "authorize_with"}.
+                             map(&:text).uniq.
+                             map {|k| [k, []]}]
+    end
+
+    def add_path_item(yard_object)
+      path = path_from_yard_object(yard_object)
+
+      return if path.nil?
+
+      path_item = (path_items[path] ||= PathItem.new(self))
+      path_item.add_operation(yard_object)
+      path
+    end
+
+    def path_from_yard_object(yard_object)
+      if tag = yard_object.tags.detect {|t| t.tag_name == "path"}
+        tag.text
+      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
+          SwaggerYard.log.warn e.message
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/swagger_yard/authorization.rb

@@ -1,34 +1,37 @@
 module SwaggerYard
   class Authorization
-    attr_reader :pass_as, :key
-    attr_writer :name
+    attr_reader :type, :name, :description
+    attr_writer :id, :key
 
     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
+    def initialize(type, name, description)
+      @type, @name, @description = type, name, description
+      @key = nil
     end
 
-    # the spec suggests most auth names are just the type of auth
-    def name
-      @name ||= [@pass_as, @key].join('_').downcase.gsub('-', '_')
+    def key
+      return @key if @key
+      return nil unless @description
+      return nil unless @type =~ /api_?key|bearer/i
+      @key, @description = @description.split(' ', 2)
+      @key
     end
 
-    def type
-      case @type
-      when "api_key"
-        "apiKey"
-      when "basic_auth"
-        "basicAuth"
-      end
+    def id
+      @id ||= api_key_id || name
     end
 
-    def to_h
-      { "type" => type,
-        "name" => @key,
-        "in"   => @pass_as }
+    private
+    def api_key_id
+      case type
+      when /api_?key/i
+        [name, key].compact.join('_').downcase.gsub('-', '_')
+      else
+        nil
+      end
     end
   end
 end

data/lib/swagger_yard/configuration.rb

@@ -3,16 +3,19 @@ module SwaggerYard
     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
     attr_accessor :security_definitions
 
+    # openapi-compatible names
+    alias openapi_version swagger_version
+    alias openapi_version= swagger_version=
+    alias security_schemes security_definitions
+    alias security_schemes= security_definitions=
+
     def initialize
       @swagger_version = "2.0"
       @api_version = "0.1"
-      @enable = false
-      @reload = true
       @title = "Configure title with SwaggerYard.config.title"
       @description = "Configure description with SwaggerYard.config.description"
       @security_definitions = {}
@@ -25,13 +28,5 @@ module SwaggerYard
       end if mappings
       @external_schema
     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/example.rb

@@ -0,0 +1,11 @@
+module SwaggerYard
+  module Example
+    def example
+      @example
+    end
+
+    def example=(val)
+      @example = JSON.parse(val) rescue val
+    end
+  end
+end

data/lib/swagger_yard/model.rb

@@ -4,7 +4,8 @@ module SwaggerYard
   #   complex model object as defined by swagger schema
   #
   class Model
-    attr_reader :id, :discriminator, :inherits, :description
+    include Example
+    attr_reader :id, :discriminator, :inherits, :description, :properties
 
     def self.from_yard_object(yard_object)
       new.tap do |model|
@@ -31,6 +32,10 @@ module SwaggerYard
       @id = Model.mangle(yard_object.path)
     end
 
+    def property(key)
+      properties.detect {|prop| prop.name == key }
+    end
+
     def parse_tags(tags)
       tags.each do |tag|
         case tag.tag_name
@@ -48,43 +53,20 @@ module SwaggerYard
           end
         when "inherits"
           @inherits << tag.text
+        when "example"
+          if tag.name && !tag.name.empty?
+            if (prop = property(tag.name))
+              prop.example = tag.text
+            else
+              SwaggerYard.log.warn("no property '#{tag.name}' defined yet to which to attach example: #{value.inspect}")
+            end
+          else
+            self.example = tag.text
+          end
         end
       end
 
       self
     end
-
-    def inherits_references
-      @inherits.map { |name| Type.new(name).to_h }
-    end
-
-    def to_h
-      h = {}
-
-      if !@properties.empty? || @inherits.empty?
-        h["type"] = "object"
-        h["properties"] = Hash[@properties.map {|p| [p.name, p.to_h]}]
-        h["required"] = @properties.select(&:required?).map(&:name) if @properties.detect(&:required?)
-      end
-
-      h["discriminator"] = @discriminator if @discriminator
-
-      # Polymorphism
-      unless @inherits.empty?
-        all_of = inherits_references
-        all_of << h unless h.empty?
-
-        if all_of.length == 1 && @description.empty?
-          h.update(all_of.first)
-        else
-          h = { "allOf" => all_of }
-        end
-      end
-
-      # Description
-      h["description"] = @description unless @description.empty?
-
-      h
-    end
   end
 end

data/lib/swagger_yard/openapi.rb

@@ -0,0 +1,120 @@
+module SwaggerYard
+  class OpenAPI < Swagger
+    def to_h
+      metadata.merge(definitions)
+    end
+
+    def model_path
+      '#/components/schemas/'
+    end
+
+    def metadata
+      {
+        'openapi' => '3.0.0',
+        'info' => Info.new.to_h,
+        'servers' => [{'url' => SwaggerYard.config.api_base_path}]
+      }
+    end
+
+    def definitions
+      {
+        "paths" => paths(specification.path_objects),
+        "tags" => tags(specification.tag_objects),
+        "components" => components
+      }
+    end
+
+    def components
+      {
+        "schemas" => models(specification.model_objects),
+        "securitySchemes" => security_defs(specification.security_objects)
+      }
+    end
+
+    def parameters(params)
+      params.select { |param| param.param_type != 'body' }.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)
+          h["schema"] = schema
+          h["explode"] = true if !Array(param.allow_multiple).empty? && schema["items"]
+        end
+      end
+    end
+
+    def operation(op)
+      op_hash = super
+      if body_param = op.parameters.detect { |p| p.param_type == 'body' }
+        op_hash['requestBody'] = {
+          'description' => body_param.description,
+          'content' => {
+            'application/json' => {
+              'schema' => body_param.type.schema_with(model_path: model_path)
+            }
+          }
+        }
+      end
+      op_hash
+    end
+
+    def response(resp, op)
+      {}.tap do |h|
+        h['description'] = resp && resp.description || op.summary || ''
+        if resp && resp.type && (schema = resp.type.schema_with(model_path: model_path))
+          h['content'] = { 'application/json' => { 'schema' => schema } }
+          h['content']['application/json']['example'] = resp.example if resp.example
+        end
+      end
+    end
+
+    def security_defs(security_objects)
+      defs = super
+      Hash[defs.map do |name, d|
+             [name, map_security(d)]
+           end]
+    end
+
+    def security(obj)
+      case obj.type
+      when /api_?key/i
+        { 'type' => 'apiKey', 'name' => obj.key, 'in' => obj.name }
+      when /bearer/i
+        { 'type' => obj.type, 'name' => obj.name, 'format' => obj.key }
+      else
+        { 'type' => obj.type, 'name' => obj.name }
+      end.tap do |result|
+        result['description'] = obj.description if obj.description && !obj.description.empty?
+      end
+    end
+
+    def map_security(h)
+      h = Hash[h.map { |k, v| [k.to_s, v] }] # quick-n-dirty stringify keys
+      case type = h['type'].to_s
+      when 'apiKey', 'http'
+        h
+      when 'oauth2'
+        # convert from swagger2-style oauth2
+        if (authUrl = h.delete('authorizationUrl')) && (flow = h.delete('flow'))
+          { 'type' => 'oauth2', 'flows' => {
+              flow => { 'authorizationUrl' => authUrl } } }.tap do |result|
+            (h.keys - ['type']).each do |t|
+              result['flows'][flow][t] = h[t]
+            end
+            result['flows'][flow]['scopes'] = {} unless result['flows'][flow]['scopes']
+          end
+        else
+          h
+        end
+      else
+        { 'type' => 'http', 'scheme' => type }.tap do |result|
+          result['bearerFormat'] = h['format'] if h['format']
+        end
+      end.tap do |result|
+        result['description'] = h['description'] unless h['description'].nil? || h['description'].empty?
+      end
+    end
+  end
+end

data/lib/swagger_yard/operation.rb

@@ -1,13 +1,19 @@
 module SwaggerYard
+  class Response
+    include Example
+    attr_accessor :status, :description, :type
+  end
+
   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
+    attr_reader :path, :http_method
+    attr_reader :parameters
+    attr_reader :path_item, :responses
 
     # TODO: extract to operation builder?
-    def self.from_yard_object(yard_object, api)
-      new(api).tap do |operation|
+    def self.from_yard_object(yard_object, path_item)
+      new(path_item).tap do |operation|
         operation.ruby_method = yard_object.name(false)
         operation.description = yard_object.docstring
         yard_object.tags.each do |tag|
@@ -20,10 +26,16 @@ module SwaggerYard
           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 "error_message", "response"
+            operation.add_response(tag)
           when "summary"
             operation.summary = tag.text
+          when "example"
+            if tag.name && !tag.name.empty?
+              operation.response(tag.name).example = tag.text
+            else
+              operation.default_response.example = tag.text
+            end
           end
         end
 
@@ -31,57 +43,47 @@ module SwaggerYard
       end
     end
 
-    def initialize(api)
-      @api            = api
+    def initialize(path_item)
+      @path_item      = path_item
       @summary        = nil
       @description    = ""
       @parameters     = []
-      @model_names    = []
-      @error_messages = []
+      @default_response = nil
+      @responses = []
     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
+    def operation_id
+      "#{api_group.resource}-#{ruby_method}"
+    end
 
-      api_decl = @api.api_declaration
+    def api_group
+      path_item.api_group
+    end
 
-      {
-        "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?
+    def tags
+      [api_group.resource].compact
+    end
 
-        authorizations = api_decl.authorizations
-        unless authorizations.empty?
-          h["security"] = authorizations.map {|k,v| { k => v} }
+    def responses_by_status
+      {}.tap do |hash|
+        hash['default'] = default_response if @default_response || @responses.empty?
+        responses.each do |response|
+          hash[response.status] = response
         end
+      end
+    end
 
+    def extended_attributes
+      {}.tap do |h|
         # 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-controller"] = api_group.class_name.constantize.controller_path.to_s
           h["x-action"]     = ruby_method.to_s
         rescue NameError, NoMethodError
         end
@@ -112,7 +114,7 @@ module SwaggerYard
     # 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)
+      param = Parameter.from_yard_tag(tag)
       add_or_update_parameter param if param
     end
 
@@ -124,29 +126,44 @@ module SwaggerYard
         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}"
+          "ignored #{parameter.name} for #{@path_item.api_group.class_name}##{ruby_method}"
       else
         @parameters << parameter
       end
     end
 
+    def default_response
+      @default_response ||= Response.new.tap do |r|
+        r.status = 'default'
+      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
+      default_response.type = type
+      default_response.description = desc
+    end
+
+    def response(name)
+      status = Integer(name)
+      resp = responses.detect { |r| r.status == status }
+      unless resp
+        resp = Response.new
+        resp.status = status
+        responses << resp
+      end
+      resp
     end
 
-    def add_error_message(tag)
+    def add_response(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?}
+      r = response(tag.name)
+      r.description = tag.text if tag.text
+      r.type = Type.from_type_list(Array(tag.types)) if tag.types
+      r
     end
 
     def sort_parameters