swaggard 0.5.4 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: ecc218894a718358cb55794cbe31c0506761fcca
-  data.tar.gz: b45ab232037649703f9b277be8104a2c9df607de
+SHA256:
+  metadata.gz: fc7e15b774e8c15ddf109dfaad4d2b3dd571e6a5527b8d237bcc89e07d5c867f
+  data.tar.gz: 1889e419f45111899943019b967ecb1ce094331a23b0fcc79fabd7e387c6e7ad
 SHA512:
-  metadata.gz: 0bdc966974f63e4b95560412522ba5fe587df415a673bc94214bb3188cea43d8439748bbd5604f7b60ccd4353e949b7d569e46fb28c9c44fd15060a6e57b2301
-  data.tar.gz: 9b3ec08e20ff8c589ec17fe6abc9f174791acb706648c4647133828313c8f2e0e54fe3ce5af416583ed51157bebd81aacbf2d7bec88e0c5c6494bb9b20ffdfbc
+  metadata.gz: 4f86d35cd4362a15b4a93bd9ac2ae4ce4a78d6bdca04823a9b3a8636903c35472944c73cde67d5e8c5ac5c05cf0c85c32aa7a25788173a52487e13aef184cc4c
+  data.tar.gz: 452ef43b35624b738762e396758dabf284b265d8e81fb0ef15f8e6ce07306a0c2a9204d1c1efc5a59028753c46aba6239d8912a988f7e7f7071d1772fcc30934

data/lib/swaggard/api_definition.rb

@@ -2,7 +2,6 @@ require_relative 'swagger/path'
 
 module Swaggard
   class ApiDefinition
-
     attr_accessor :definitions
 
     def initialize
@@ -23,32 +22,45 @@ module Swaggard
       @definitions.concat(operation.definitions)
     end
 
+    def ignore_put_if_patch!
+      @paths.values.each(&:ignore_put_if_patch!)
+    end
+
     def to_doc
+      contact = { 'name'  => Swaggard.configuration.contact_name }
+      contact['email'] = Swaggard.configuration.contact_email if Swaggard.configuration.contact_email.present?
+      contact['url'] = Swaggard.configuration.contact_url if Swaggard.configuration.contact_url.present?
+
+      license = { 'name'  => Swaggard.configuration.license_name }
+      license['url'] = Swaggard.configuration.license_url if Swaggard.configuration.license_url.present?
+
       {
         'swagger' => Swaggard.configuration.swagger_version,
         'info' => {
-          'description'     => Swaggard.configuration.description,
           'version'         => Swaggard.configuration.api_version,
           'title'           => Swaggard.configuration.title,
+          'description'     => Swaggard.configuration.description,
           'termsOfService'  => Swaggard.configuration.tos,
-          'contact' => {
-            'name'  => Swaggard.configuration.contact_name,
-            'email' => Swaggard.configuration.contact_email,
-            'url'   => Swaggard.configuration.contact_url
-          },
-          'license' => {
-            'name'  => Swaggard.configuration.license_name,
-            'url'   => Swaggard.configuration.license_url
-          }
+          'contact'         => contact,
+          'license'         => license,
         },
         'host'        => Swaggard.configuration.host,
         'basePath'    => Swaggard.configuration.api_base_path,
-        'tags'        => @tags.map { |_, tag| tag.to_doc },
         'schemes'     => Swaggard.configuration.schemes,
-        'paths'       => Hash[@paths.values.map { |path| [path.path, path.to_doc] }],
+        'consumes'    => Swaggard.configuration.api_formats.map { |format| "application/#{format}" },
+        'produces'    => Swaggard.configuration.api_formats.map { |format| "application/#{format}" },
+        'tags'        => @tags.map { |_, tag| tag.to_doc },
+        'paths'       => Hash[@paths.values.map { |path| [format_path(path.path), path.to_doc] }],
         'definitions' => Hash[@definitions.map { |definition| [definition.id, definition.to_doc] }]
       }
     end
 
+    private
+
+    def format_path(path)
+      return path unless Swaggard.configuration.exclude_base_path_from_paths
+
+      path.gsub(Swaggard.configuration.api_base_path, '')
+    end
   end
-end
+end

data/lib/swaggard/configuration.rb

@@ -18,7 +18,12 @@ module Swaggard
                 :description, :tos, :contact_email, :contact_name, :contact_url, :host,
                 :authentication_type, :authentication_key, :authentication_value,
                 :access_username, :access_password, :default_content_type, :use_cache,
-                :language, :additional_parameters, :schemes
+                :language, :additional_parameters, :schemes, :ignore_undocumented_paths,
+                :license_name, :exclude_base_path_from_paths, :default_response_description,
+                :default_response_status_code, :excluded_paths, :path_parameter_description,
+                :ignore_put_if_patch_exists
+
+    attr_reader :custom_types
 
     def swagger_version
       @swagger_version ||= '2.0'
@@ -65,7 +70,7 @@ module Swaggard
     end
 
     def contact_url
-      @contact_email ||= ''
+      @contact_url ||= ''
     end
 
     def license_name
@@ -100,6 +105,26 @@ module Swaggard
       @default_content_type ||= ''
     end
 
+    def default_response_status_code
+      @default_response_status_code ||= 'default'
+    end
+
+    def default_response_description
+      @default_response_description ||= 'successful operation'
+    end
+
+    def ignore_undocumented_paths
+      return @ignore_undocumented_paths unless @ignore_undocumented_paths.nil?
+
+      @ignore_undocumented_paths = false
+    end
+
+    def exclude_base_path_from_paths
+      return @exclude_base_path_from_paths unless @exclude_base_path_from_paths.nil?
+
+      @exclude_base_path_from_paths = false
+    end
+
     def language
       @language ||= 'en'
     end
@@ -112,5 +137,26 @@ module Swaggard
       @use_cache ||= false
     end
 
+    def custom_types
+      @custom_types ||= {}
+    end
+
+    def excluded_paths
+      @excluded_paths ||= []
+    end
+
+    def add_custom_type(name, definition)
+      custom_types[name] = definition
+    end
+
+    def path_parameter_description
+      @path_parameter_description ||= ->(path_parameter) { "Scope response to #{path_parameter.name}" }
+    end
+
+    def ignore_put_if_patch_exists
+      return @ignore_put_if_patch_exists unless @ignore_put_if_patch_exists.nil?
+
+      @ignore_put_if_patch_exists = false
+    end
   end
 end

data/lib/swaggard/parsers/{controllers.rb → controller.rb}

@@ -3,23 +3,21 @@ require_relative '../swagger/tag'
 
 module Swaggard
   module Parsers
-    class Controllers
+    class Controller
 
-      def run(yard_objects, routes)
+      def run(yard_objects)
         tag = nil
-        operations = []
+        operations = {}
 
         yard_objects.each do |yard_object|
           if yard_object.type == :class
             tag = Swagger::Tag.new(yard_object)
           elsif tag && yard_object.type == :method
-            operation = Swagger::Operation.new(yard_object, tag, routes)
-            operations << operation if operation.valid?
+            name = yard_object.name
+            operations[name.to_s] = yard_object
           end
         end
 
-        return unless operations.any?
-
         return tag, operations
       end
 

data/lib/swaggard/parsers/routes.rb

@@ -5,21 +5,22 @@ module Swaggard
       def run(routes)
         return {} unless routes
 
-        parsed_routes = {}
-
-        routes.each do |route|
-          controller = route_controller(route)
-          action = route_action(route)
-
-          parsed_routes[controller] ||= {}
-          parsed_routes[controller][action] = {
-            verb:         route_verb(route),
-            path:         route_path(route),
-            path_params:  route_path_params(route)
-          }
-        end
-
-        parsed_routes
+        routes.inject({}) do |parsed_routes, route|
+          path = route_path(route)
+
+          unless Swaggard.configuration.excluded_paths.any? { |excluded_path| Regexp.new(excluded_path) =~ path }
+            verb = route_verb(route)
+
+            parsed_routes[path] ||= {}
+            parsed_routes[path][verb] = {
+              controller:   route_controller(route),
+              action:       route_action(route),
+              path_params:  route_path_params(route)
+            }
+          end
+
+          parsed_routes
+        end.sort.to_h
       end
 
       private

data/lib/swaggard/swagger/definition.rb

@@ -3,24 +3,37 @@ module Swaggard
     class Definition
 
       attr_reader :id
+      attr_writer :description, :title
 
       def initialize(id)
         @id = id
+        @title = ''
         @properties = []
+        @description = ''
       end
 
       def add_property(property)
         @properties << property
       end
 
+      def empty?
+        @properties.empty?
+      end
+
       def to_doc
-        {
-          'type'        => 'object',
-          'required'    => [],
-          'properties'  => Hash[@properties.map { |property| [property.id, property.to_doc] }]
-        }
+        {}.tap do |doc|
+          doc['title'] = @title if @title.present?
+          doc['type']  = 'object'
+
+          doc['description'] = @description if @description.present?
+
+          doc['properties'] =  Hash[@properties.map { |property| [property.id, property.to_doc] }]
+          required_properties = @properties.select(&:required?).map(&:id)
+          doc['required'] = required_properties if required_properties.any?
+        end
+
       end
 
     end
   end
-end
+end

data/lib/swaggard/swagger/operation.rb

@@ -9,28 +9,42 @@ require_relative 'response'
 module Swaggard
   module Swagger
     class Operation
-
       attr_reader :nickname
       attr_accessor :path, :parameters, :description, :http_method, :summary, :notes,
                     :error_responses, :tag
 
-      def initialize(yard_object, tag, routes)
+      def initialize(yard_object, tag, path, verb, path_params)
         @name = yard_object.name
         @tag = tag
-        @summary = yard_object.docstring.lines.first || ''
+        @summary = (yard_object.docstring.lines.first || '').chomp
         @parameters  = []
         @responses = []
-        @description = (yard_object.docstring.lines[1..-1] || []).join("\n")
+
+        @description = (yard_object.docstring.lines[1..-1] || []).map(&:chomp).reject(&:empty?).compact.join("\n")
         @formats = Swaggard.configuration.api_formats
+        @http_method = verb
+        @path = path
+
+        build_path_parameters(path_params)
 
         yard_object.tags.each do |yard_tag|
           value = yard_tag.text
 
           case yard_tag.tag_name
+          when 'operation_id'
+            @operation_id = value
           when 'query_parameter'
             @parameters << Parameters::Query.new(value)
           when 'form_parameter'
             @parameters << Parameters::Form.new(value)
+          when 'body_required'
+            body_parameter.is_required = true
+          when 'body_description'
+            body_parameter.description = value
+          when 'body_title'
+            body_parameter.title = value
+          when 'body_definition'
+            body_parameter.definition = value
           when 'body_parameter'
             body_parameter.add_property(value)
           when 'parameter_list'
@@ -41,11 +55,15 @@ module Swaggard
             success_response.status_code = value
           when 'response_root'
             success_response.response_root = value
+          when 'response_description'
+            success_response.description = value
+          when 'response_example'
+            success_response.add_example(value)
+          when 'response_header'
+            success_response.add_header(value)
           end
         end
 
-        build_path_parameters(routes)
-
         @parameters.sort_by { |parameter| parameter.name }
 
         @responses << success_response
@@ -55,20 +73,22 @@ module Swaggard
         @path.present?
       end
 
-      def to_doc
-        produces = @formats.map { |format| "application/#{format}" }
-        consumes = @formats.map { |format| "application/#{format}" }
+      def empty?
+        @summary.blank? && @description.blank?
+      end
 
+      def to_doc
         {
           'tags'           => [@tag.name],
+          'operationId'    => @operation_id || @name,
           'summary'        => @summary,
           'description'    => @description,
-          'operationId'    => @name,
-          'consumes'       => consumes,
-          'produces'       => produces,
-          'parameters'     => @parameters.map(&:to_doc),
-          'responses'      => Hash[@responses.map { |response| [response.status_code, response.to_doc] }]
-        }
+          'produces'       => @formats.map { |format| "application/#{format}" },
+        }.tap do |doc|
+          doc['consumes'] = @formats.map { |format| "application/#{format}" } if @body_parameter
+          doc['parameters'] = @parameters.map(&:to_doc)
+          doc['responses'] = Hash[@responses.map { |response| [response.status_code, response.to_doc] }]
+        end
       end
 
       def definitions
@@ -92,19 +112,11 @@ module Swaggard
         @body_parameter
       end
 
-      def build_path_parameters(routes)
+      def build_path_parameters(path_params)
         return unless @tag.controller_class
 
-        route = (routes[@tag.controller_class.controller_path] || {})[@name.to_s]
-
-        return unless route
-
-        @http_method = route[:verb]
-        @path = route[:path]
-
-        route[:path_params].each { |path_param| @parameters << Parameters::Path.new(path_param) }
+        path_params.each { |path_param| @parameters << Parameters::Path.new(self, path_param) }
       end
-
     end
   end
 end

data/lib/swaggard/swagger/parameters/base.rb

@@ -3,19 +3,20 @@ module Swaggard
     module Parameters
       class Base
 
-        attr_reader :name
+        attr_reader :name, :description
+        attr_writer :is_required
 
         def to_doc
           {
-            'in'            => @in,
             'name'          => @name,
-            'description'   => @description,
+            'in'            => @in,
             'required'      => @is_required,
-            'type'          => @data_type
+            'type'          => @data_type,
+            'description'   => description
           }
         end
 
       end
     end
   end
-end
+end

data/lib/swaggard/swagger/parameters/body.rb

@@ -9,10 +9,12 @@ module Swaggard
         attr_reader :definition
 
         def initialize(operation_name)
-          @in           = 'body'
-          @name         = 'body'
-          @description  = ''
-          @definition   = Definition.new("#{operation_name}_body")
+          @in             = 'body'
+          @name           = 'body'
+          @is_required    = false
+          @description    = ''
+          @definition     = Definition.new("#{operation_name}_body")
+          @definition_id  = @definition.id
         end
 
         def add_property(string)
@@ -20,17 +22,33 @@ module Swaggard
           @definition.add_property(property)
         end
 
+        def empty?
+          @definition.empty?
+        end
+
         def to_doc
           doc = super
 
           doc.delete('type')
+          doc.delete('description')
 
-          doc['required'] = false
-          doc['schema'] = { '$ref' => "#/definitions/#{@definition.id}" }
+          doc['schema'] = { '$ref' => "#/definitions/#{@definition_id}" }
 
           doc
         end
 
+        def description=(description)
+          @definition.description = description
+        end
+
+        def title=(title)
+          @definition.title = title
+        end
+
+        def definition=(definition)
+          @definition_id = definition
+        end
+
         private
 
 
@@ -42,9 +60,14 @@ module Swaggard
             parse(string)
           end
 
+          def required?
+            @required
+          end
+
           def to_doc
             result = @type.to_doc
             result['description'] = @description if @description
+            result['enum'] = @options if @options.present?
             result
           end
 
@@ -52,13 +75,16 @@ module Swaggard
           # 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(string)
-            data_type, name, description = string.split
-
-            data_type.gsub!('[', '').gsub!(']', '')
+            data_type, required, name, options_and_description = string.match(/\A\[(\S*)\](!)?\s*([\w\[\]]*)\s*(.*)\Z/).captures
+            allow_multiple = name.gsub!('[]', '')
+            options, description = options_and_description.match(/\A(\[.*\])?(.*)\Z/).captures
+            options = options ? options.gsub(/\[?\]?\s?/, '').split(',') : []
 
             @id = name
-            @description = description
+            @description = description if description.present?
             @type = Type.new([data_type])
+            @required = required
+            @options = options
           end
 
         end

data/lib/swaggard/swagger/parameters/form.rb

@@ -29,4 +29,4 @@ module Swaggard
       end
     end
   end
-end
+end

data/lib/swaggard/swagger/parameters/list.rb

@@ -4,7 +4,6 @@ module Swaggard
   module Swagger
     module Parameters
       class List < Base
-
         def initialize(string)
           @in = 'query'
           parse(string)
@@ -39,8 +38,7 @@ module Swaggard
           @data_type = data_type.downcase
           @is_required = required.present?
         end
-
       end
     end
   end
-end
+end

data/lib/swaggard/swagger/parameters/path.rb

@@ -5,17 +5,30 @@ module Swaggard
     module Parameters
       class Path < Base
 
-        attr_reader :name
+        attr_reader :operation, :name
 
-        def initialize(param_name)
+        def initialize(operation, param_name)
+          @operation = operation
           @in = 'path'
           @name = param_name.to_s
           @data_type = 'string'
           @is_required = true
-          @description = "Scope response to #{@name}"
         end
 
+        def description
+          @description ||= get_description
+        end
+
+        private
+
+        def get_description
+          if Swaggard.configuration.path_parameter_description.respond_to?(:call)
+            Swaggard.configuration.path_parameter_description.call(self)
+          else
+            Swaggard.configuration.path_parameter_description
+          end
+        end
       end
     end
   end
-end
+end

data/lib/swaggard/swagger/parameters/query.rb

@@ -11,11 +11,16 @@ module Swaggard
         end
 
         def to_doc
-          doc = super
-
-          doc.merge!('enum' => @options) if @options.any?
-
-          doc
+          {
+            'name'          => @name,
+            'in'            => @in,
+            'required'      => @is_required,
+          }.tap do |doc|
+            doc.merge!(@type.to_doc)
+
+            doc.merge!('enum' => @options) if @options.any?
+            doc.merge!('description'   => description)
+          end
         end
 
         private
@@ -24,7 +29,7 @@ module Swaggard
         # 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(string)
-          data_type, name, required, options_and_description = string.match(/\A\[(\S*)\]\s*([\w\[\]]*)(\(required\))?\s*(.*)\Z/).captures
+          data_type, required, name, options_and_description = string.match(/\A\[(\S*)\](!)?\s*([\w\[\]]*)\s*(.*)\Z/).captures
           allow_multiple = name.gsub!('[]', '')
 
           options, description = options_and_description.match(/\A(\[.*\])?(.*)\Z/).captures
@@ -32,7 +37,7 @@ module Swaggard
 
           @name = name
           @description = description
-          @data_type = data_type.downcase
+          @type = Type.new([data_type])
           @is_required = required.present?
           @allow_multiple = allow_multiple.present?
           @options = options
@@ -41,4 +46,4 @@ module Swaggard
       end
     end
   end
-end
+end

data/lib/swaggard/swagger/path.rb

@@ -3,7 +3,6 @@ require_relative 'operation'
 module Swaggard
   module Swagger
     class Path
-
       attr_reader :path
 
       def initialize(path)
@@ -15,10 +14,13 @@ module Swaggard
         @operations[operation.http_method.downcase] = operation
       end
 
+      def ignore_put_if_patch!
+        @operations.delete('put') if @operations.key?('patch')
+      end
+
       def to_doc
         Hash[@operations.map { |http_method, operation| [http_method, operation.to_doc] }]
       end
-
     end
   end
-end
+end

data/lib/swaggard/swagger/property.rb

@@ -7,14 +7,29 @@ module Swaggard
       attr_reader :id, :type, :description
 
       def initialize(yard_object)
-        @id = yard_object.name
+        name = yard_object.name.dup
+        options_and_description = yard_object.text&.dup || ''
+
+        options, description = options_and_description.match(/\A(\[.*\])?(.*)\Z/).captures
+        options = options ? options.gsub(/\[?\]?\s?/, '').split(',') : []
+        description = description.strip
+        required = name.gsub!(/^!/, '')
+
+        @id = name
         @type = Type.new(yard_object.types)
-        @description = yard_object.text
+        @description = description
+        @required = required.present?
+        @options = options
+      end
+
+      def required?
+        @required
       end
 
       def to_doc
         result = @type.to_doc
-        result['description'] = @description if @description
+        result['description'] = @description if @description.present?
+        result['enum'] = @options if @options.present?
         result
       end
 

data/lib/swaggard/swagger/response.rb

@@ -1,9 +1,9 @@
+require_relative 'response_header'
+
 module Swaggard
   module Swagger
     class Response
 
-      DEFAULT_STATUS_CODE = 'default'
-      DEFAULT_DESCRIPTION = 'successful operation'
       PRIMITIVE_TYPES = %w[integer long float double string byte binary boolean date date-time password hash]
 
       attr_writer :status_code, :description
@@ -11,6 +11,7 @@ module Swaggard
       def initialize(operation_name)
         @operation_name = operation_name
         @response_model = ResponseModel.new
+        @headers = []
       end
 
       def definition
@@ -22,7 +23,7 @@ module Swaggard
       end
 
       def status_code
-        @status_code || DEFAULT_STATUS_CODE
+        @status_code || Swaggard.configuration.default_response_status_code
       end
 
       def response_class=(value)
@@ -34,8 +35,16 @@ module Swaggard
         @response_model.id = root
       end
 
+      def add_example(value)
+        @example = value
+      end
+
+      def add_header(value)
+        @headers << ResponseHeader.new(value)
+      end
+
       def description
-        @description || DEFAULT_DESCRIPTION
+        @description || Swaggard.configuration.default_response_description
       end
 
       def to_doc
@@ -47,6 +56,18 @@ module Swaggard
                    end
 
           doc.merge!('schema' => schema) if schema
+          doc.merge!('examples' => example_to_doc) if @example
+          if @headers.any?
+            doc['headers'] = Hash[@headers.map { |header| [header.name, header.to_doc] }]
+          end
+        end
+      end
+
+      def example_to_doc
+        Swaggard.configuration.api_formats.inject({}) do |examples, format|
+          examples.merge!("application/#{format}" => { '$ref' => @example })
+
+          examples
         end
       end
 

data/lib/swaggard/swagger/response_header.rb

@@ -0,0 +1,37 @@
+module Swaggard
+  module Swagger
+    class ResponseHeader
+      attr_reader :name
+
+      def initialize(string)
+        parse(string)
+      end
+
+      def to_doc
+        {
+          'description' => @description,
+          'type'        => @type,
+        }
+      end
+
+      private
+
+      # Example: [Array]     status            Filter by status. (e.g. status[]=1&status[]=2&status[]=3)
+      # Example: [Array]!    status  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(string)
+        data_type, name, options_and_description = string.match(/\A\[(\S*)\]\s*([\w\-\[\]]*)\s*(.*)\Z/).captures
+        allow_multiple = name.gsub!('[]', '')
+
+        options, description = options_and_description.match(/\A(\[.*\])?(.*)\Z/).captures
+        options = options ? options.gsub(/\[?\]?\s?/, '').split(',') : []
+
+        @name = name
+        @description = description
+        @type = data_type
+        @allow_multiple = allow_multiple.present?
+        @options = options
+      end
+    end
+  end
+end

data/lib/swaggard/swagger/type.rb

@@ -1,7 +1,6 @@
 module Swaggard
   module Swagger
     class Type
-
       BASIC_TYPES = {
         'integer'   => { 'type' => 'integer', 'format' => 'int32' },
         'long'      => { 'type' => 'integer', 'format' => 'int64' },
@@ -31,10 +30,6 @@ module Swaggard
         end
       end
 
-      def basic_type?
-        BASIC_TYPES.has_key?(@name.downcase)
-      end
-
       private
 
       def parse(types)
@@ -44,14 +39,24 @@ module Swaggard
         @is_array = parts.grep(/array/i).any?
       end
 
+
+      def basic_type?
+        BASIC_TYPES.has_key?(@name.downcase)
+      end
+
+      def custom_type?
+        Swaggard.configuration.custom_types.has_key?(@name)
+      end
+
       def type_tag_and_name
         if basic_type?
-          BASIC_TYPES[@name.downcase]
+          BASIC_TYPES[@name.downcase].dup
+        elsif custom_type?
+          Swaggard.configuration.custom_types[@name].dup
         else
           { '$ref' => "#/definitions/#{name}" }
         end
       end
-
     end
   end
-end
+end

data/lib/swaggard/version.rb

@@ -1,5 +1,3 @@
 module Swaggard
-
-  VERSION = '0.5.4'
-
+  VERSION = '1.0.0'
 end

data/lib/swaggard.rb

@@ -5,7 +5,7 @@ require 'swaggard/api_definition'
 require 'swaggard/configuration'
 require 'swaggard/engine'
 
-require 'swaggard/parsers/controllers'
+require 'swaggard/parsers/controller'
 require 'swaggard/parsers/models'
 require 'swaggard/parsers/routes'
 
@@ -22,22 +22,30 @@ module Swaggard
 
     # Register some custom yard tags
     def register_custom_yard_tags!
-      ::YARD::Tags::Library.define_tag('Controller\'s tag',  :tag)
+      ::YARD::Tags::Library.define_tag('Controller\'s tag', :tag)
+      ::YARD::Tags::Library.define_tag('Operation id', :operation_id)
       ::YARD::Tags::Library.define_tag('Query parameter', :query_parameter)
-      ::YARD::Tags::Library.define_tag('Form parameter',  :form_parameter)
-      ::YARD::Tags::Library.define_tag('Body parameter',  :body_parameter)
-      ::YARD::Tags::Library.define_tag('Parameter list',  :parameter_list)
-      ::YARD::Tags::Library.define_tag('Response class',  :response_class)
-      ::YARD::Tags::Library.define_tag('Response Root',  :response_root)
-      ::YARD::Tags::Library.define_tag('Response Status',  :response_status)
+      ::YARD::Tags::Library.define_tag('Form parameter', :form_parameter)
+      ::YARD::Tags::Library.define_tag('Body required', :body_required)
+      ::YARD::Tags::Library.define_tag('Body description', :body_description)
+      ::YARD::Tags::Library.define_tag('Body title', :body_title)
+      ::YARD::Tags::Library.define_tag('Body definition', :body_definition)
+      ::YARD::Tags::Library.define_tag('Body parameter', :body_parameter)
+      ::YARD::Tags::Library.define_tag('Parameter list', :parameter_list)
+      ::YARD::Tags::Library.define_tag('Response class', :response_class)
+      ::YARD::Tags::Library.define_tag('Response root', :response_root)
+      ::YARD::Tags::Library.define_tag('Response status', :response_status)
+      ::YARD::Tags::Library.define_tag('Response description', :response_description)
+      ::YARD::Tags::Library.define_tag('Response example', :response_example)
+      ::YARD::Tags::Library.define_tag('Response header', :response_header)
     end
 
-    def get_doc(host)
+    def get_doc(host = nil)
       load!
 
       doc = @api.to_doc
 
-      doc['host'] = host if doc['host'].blank?
+      doc['host'] = host if doc['host'].blank? && host
 
       doc
     end
@@ -48,22 +56,67 @@ module Swaggard
       @api = Swaggard::ApiDefinition.new
 
       parse_models
-      parse_controllers
+      build_operations
+
+      @api.ignore_put_if_patch! if Swaggard.configuration.ignore_put_if_patch_exists
     end
 
-    def parse_controllers
-      parser = Parsers::Controllers.new
+    def build_operation(path, verb, route)
+      controller_name = route[:controller]
+      action_name = route[:action]
+
+      return unless controllers[controller_name]
+
+      controller_tag = controllers[controller_name][:tag]
+
+      return unless controller_tag
+
+      return unless controllers[controller_name][:operations]
+
+      return unless controllers[controller_name][:operations][action_name]
 
+      operation_yard_object = controllers[controller_name][:operations][action_name]
+
+      return unless operation_yard_object
+
+      operation = Swagger::Operation.new(operation_yard_object, controller_tag, path, verb, route[:path_params])
+
+      return unless operation.valid?
+      return if Swaggard.configuration.ignore_undocumented_paths && operation.empty?
+
+      return controller_tag, operation
+    end
+
+    def build_operations
+      routes.each do |path, verbs|
+        verbs.each do |verb, route_options|
+          tag, operation = build_operation(path, verb, route_options)
+
+          next unless tag
+
+          @api.add_tag(tag)
+          @api.add_operation(operation)
+        end
+      end
+    end
+
+    def controllers
+      return @controllers if @controllers
+
+      parser = Parsers::Controller.new
+
+      @controllers = {}
       Dir[configuration.controllers_path].each do |file|
         yard_objects = get_yard_objects(file)
 
-        tag, operations = parser.run(yard_objects, routes)
+        tag, operations = parser.run(yard_objects)
 
         next unless tag
 
-        @api.add_tag(tag)
-        operations.each { |operation| @api.add_operation(operation) }
+        @controllers[tag.controller_class.controller_path] ||= { tag: tag, operations: operations }
       end
+
+      @controllers
     end
 
     def routes

data/lib/tasks/swaggard.rake

@@ -6,4 +6,10 @@ namespace :swaggard do
     puts 'Swaggard cache has been cleared'
   end
 
-end
+  desc 'Dump swagger.json'
+  task :dump => :environment do
+    swagger = Swaggard.get_doc
+    File.open('public/swagger/swaggard.json', 'w') { |file| file.write(JSON.pretty_generate(swagger)) }
+    puts 'Swaggard dump complete'
+  end
+end

data/spec/fixtures/api.json

@@ -1 +1 @@
-{"swagger":"2.0","info":{"description":"","version":"0.1","title":"","termsOfService":"","contact":{"name":"","email":"","url":""},"license":{"name":"","url":""}},"host":"localhost:3000","basePath":"/","tags":[{"name":"admin/pets","description":"This document describes the API for interacting with Pet resources"},{"name":"pets","description":"This document describes the API for interacting with Pet resources"}],"schemes":["https","http"],"paths":{"/admin/pets":{"get":{"tags":["admin/pets"],"summary":"return a list of Pets","description":"","operationId":"index","consumes":["application/xml","application/json"],"produces":["application/xml","application/json"],"parameters":[],"responses":{"default":{"description":"successful operation"}}}},"/pets":{"get":{"tags":["pets"],"summary":"return a list of Pets","description":"","operationId":"index","consumes":["application/xml","application/json"],"produces":["application/xml","application/json"],"parameters":[],"responses":{"default":{"description":"successful operation"}}}},"/pets/{id}":{"get":{"tags":["pets"],"summary":"return a Pet","description":"","operationId":"show","consumes":["application/xml","application/json"],"produces":["application/xml","application/json"],"parameters":[{"in":"query","name":"id","description":"The ID for the Pet","required":false,"type":"integer"},{"in":"path","name":"id","description":"Scope response to id","required":true,"type":"string"}],"responses":{"default":{"description":"successful operation"}}}}},"definitions":{}}
+{"swagger":"2.0","info":{"version":"0.1","title":"","description":"","termsOfService":"","contact":{"name":""},"license":{"name":""}},"host":"localhost:3000","basePath":"/","schemes":["https","http"],"consumes":["application/xml","application/json"],"produces":["application/xml","application/json"],"tags":[{"name":"admin/pets","description":"This document describes the API for interacting with Pet resources"},{"name":"pets","description":"This document describes the API for interacting with Pet resources"}],"paths":{"/admin/pets":{"get":{"tags":["admin/pets"],"operationId":"index","summary":"return a list of Pets","description":"","produces":["application/xml","application/json"],"parameters":[],"responses":{"default":{"description":"successful operation"}}}},"/pets":{"get":{"tags":["pets"],"operationId":"index","summary":"return a list of Pets","description":"","produces":["application/xml","application/json"],"parameters":[],"responses":{"default":{"description":"successful operation"}}}},"/pets/{id}":{"get":{"tags":["pets"],"operationId":"show","summary":"return a Pet","description":"","produces":["application/xml","application/json"],"parameters":[{"name":"id","in":"path","required":true,"type":"string","description":"Scope response to id"},{"name":"id","in":"query","required":false,"type":"integer","format":"int32","description":"The ID for the Pet"}],"responses":{"default":{"description":"successful operation"}}}}},"definitions":{}}

data/spec/integration/swaggard_spec.rb

@@ -3,7 +3,6 @@ require 'spec_helper'
 require 'json-schema'
 
 describe Swaggard, '.get_doc' do
-
   let(:controller_path) { File.expand_path('../../fixtures/dummy/app/controllers/**/*.rb', __FILE__) }
   let(:api_json)        { File.read(File.expand_path('../../fixtures/api.json', __FILE__)) }
 
@@ -19,5 +18,4 @@ describe Swaggard, '.get_doc' do
 
     expect(swagger_json).to eq(api_json)
   end
-
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: swaggard
 version: !ruby/object:Gem::Version
-  version: 0.5.4
+  version: 1.0.0
 platform: ruby
 authors:
 - Adrian Gomez
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-07-18 00:00:00.000000000 Z
+date: 2019-07-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -166,7 +166,7 @@ files:
 - lib/swaggard/api_definition.rb
 - lib/swaggard/configuration.rb
 - lib/swaggard/engine.rb
-- lib/swaggard/parsers/controllers.rb
+- lib/swaggard/parsers/controller.rb
 - lib/swaggard/parsers/models.rb
 - lib/swaggard/parsers/routes.rb
 - lib/swaggard/swagger/definition.rb
@@ -180,6 +180,7 @@ files:
 - lib/swaggard/swagger/path.rb
 - lib/swaggard/swagger/property.rb
 - lib/swaggard/swagger/response.rb
+- lib/swaggard/swagger/response_header.rb
 - lib/swaggard/swagger/tag.rb
 - lib/swaggard/swagger/type.rb
 - lib/swaggard/version.rb
@@ -214,20 +215,19 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.5.1
+rubygems_version: 3.0.3
 signing_key: 
 specification_version: 4
 summary: 'Swaggard: Swagger Rails REST API doc using yard YARD'
 test_files:
-- spec/fixtures/api.json
-- spec/fixtures/dummy/app/controllers/admin/pets_controller.rb
-- spec/fixtures/dummy/app/controllers/application_controller.rb
+- spec/spec_helper.rb
+- spec/integration/swaggard_spec.rb
+- spec/fixtures/swagger_schema.json
 - spec/fixtures/dummy/app/controllers/pets_controller.rb
-- spec/fixtures/dummy/config/application.rb
-- spec/fixtures/dummy/config/environments/development.rb
+- spec/fixtures/dummy/app/controllers/application_controller.rb
+- spec/fixtures/dummy/app/controllers/admin/pets_controller.rb
 - spec/fixtures/dummy/config/routes.rb
+- spec/fixtures/dummy/config/environments/development.rb
+- spec/fixtures/dummy/config/application.rb
 - spec/fixtures/dummy/log/development.log
-- spec/fixtures/swagger_schema.json
-- spec/integration/swaggard_spec.rb
-- spec/spec_helper.rb
+- spec/fixtures/api.json