swaggard 2.0.0 → 4.0.0

data/lib/swaggard/swagger/operation.rb

@@ -14,14 +14,13 @@ module Swaggard
                     :error_responses, :tag
 
       def initialize(yard_object, tag, path, verb, path_params)
-        @name = yard_object.name
+        @name = yard_object.name.to_s
         @tag = tag
         @summary = (yard_object.docstring.lines.first || '').chomp
         @parameters  = []
         @responses = []
 
         @description = (yard_object.docstring.lines[1..-1] || []).map(&:chomp).reject(&:empty?).compact.join("\n")
-        @formats = Swaggard.configuration.api_formats
         @http_method = verb
         @path = path
 
@@ -78,17 +77,26 @@ module Swaggard
       end
 
       def to_doc
-        {
-          'tags'           => [@tag.name],
-          'operationId'    => @operation_id || @name,
-          'summary'        => @summary,
-          'description'    => @description,
-          '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] }]
+        regular_params = @parameters.reject { |p| p.is_a?(Parameters::Body) || p.is_a?(Parameters::Form) }
+        body_param = @parameters.find { |p| p.is_a?(Parameters::Body) }
+        form_params = @parameters.select { |p| p.is_a?(Parameters::Form) }
+
+        doc = {
+          'tags'        => [@tag.name],
+          'operationId' => @operation_id || @name,
+          'summary'     => @summary,
+          'description' => @description,
+          'parameters'  => regular_params.map(&:to_doc),
+          'responses'   => Hash[@responses.map { |response| [response.status_code, response.to_doc] }]
+        }
+
+        if body_param && !body_param.empty?
+          doc['requestBody'] = body_param.to_request_body
+        elsif form_params.any?
+          doc['requestBody'] = build_form_request_body(form_params)
         end
+
+        doc
       end
 
       def definitions
@@ -117,6 +125,18 @@ module Swaggard
         @body_parameter
       end
 
+      def build_form_request_body(form_params)
+        properties = form_params.each_with_object({}) do |param, props|
+          props[param.name] = param.form_property_doc
+        end
+        required = form_params.select(&:is_required?).map(&:name)
+
+        schema = { 'type' => 'object', 'properties' => properties }
+        schema['required'] = required if required.any?
+
+        { 'content' => { 'application/x-www-form-urlencoded' => { 'schema' => schema } } }
+      end
+
       def build_path_parameters(path_params)
         return unless @tag.controller_class
 

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

@@ -7,13 +7,14 @@ module Swaggard
         attr_writer :is_required
 
         def to_doc
-          {
-            'name'          => @name,
-            'in'            => @in,
-            'required'      => @is_required,
-            'type'          => @data_type,
-            'description'   => description
+          doc = {
+            'name'        => @name,
+            'in'          => @in,
+            'required'    => @is_required,
+            'description' => description
           }
+          doc['schema'] = { 'type' => @data_type } if @data_type
+          doc
         end
 
       end

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

@@ -25,15 +25,15 @@ module Swaggard
           @definition.empty?
         end
 
-        def to_doc
-          doc = super
-
-          doc.delete('type')
-          doc.delete('description')
-
-          doc['schema'] = { '$ref' => "#/definitions/#{@definition_id}" }
-
-          doc
+        def to_request_body
+          {
+            'required' => @is_required,
+            'content'  => {
+              'application/json' => {
+                'schema' => { '$ref' => "#/components/schemas/#{Swaggard.ref_name(@definition_id)}" }
+              }
+            }
+          }
         end
 
         def description=(description)

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

@@ -6,10 +6,19 @@ module Swaggard
       class Form < Base
 
         def initialize(string)
-          @in = 'formData'
           parse(string)
         end
 
+        def is_required?
+          @is_required
+        end
+
+        def form_property_doc
+          doc = { 'type' => @data_type }
+          doc['description'] = @description if @description.present?
+          doc
+        end
+
         private
 
         # Example: [Array]     status            Filter by status. (e.g. status[]=1&status[]=2&status[]=3)

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

@@ -11,14 +11,12 @@ module Swaggard
 
         def to_doc
           doc = super
-
-          doc.merge(
-            {
-              'type'            => 'array',
-              'items'           => { 'type' => @data_type },
-              'enum'            => @list_values
-            }
-          )
+          doc['schema'] = {
+            'type'  => 'array',
+            'items' => { 'type' => @data_type },
+            'enum'  => @list_values
+          }
+          doc
         end
 
         private

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

@@ -11,16 +11,16 @@ module Swaggard
         end
 
         def to_doc
-          {
-            'name'          => @name,
-            'in'            => @in,
-            'required'      => @is_required,
-          }.tap do |doc|
-            doc.merge!(@type.to_doc)
+          schema = @type.to_doc
+          schema['enum'] = @options if @options.any?
 
-            doc.merge!('enum' => @options) if @options.any?
-            doc.merge!('description'   => description)
-          end
+          {
+            'name'        => @name,
+            'in'          => @in,
+            'required'    => @is_required,
+            'description' => description,
+            'schema'      => schema
+          }
         end
 
         private

data/lib/swaggard/swagger/response.rb

@@ -50,13 +50,20 @@ module Swaggard
       def to_doc
         { 'description' => description }.tap do |doc|
           schema = if @response_root.present?
-                     { '$ref' => "#/definitions/#{definition.id}" }
+                     { '$ref' => "#/components/schemas/#{Swaggard.ref_name(definition.id)}" }
                    elsif @response_model.response_class.present?
                      @response_model.to_doc
                    end
 
-          doc.merge!('schema' => schema) if schema
-          doc.merge!('examples' => example_to_doc) if @example
+          if schema || @example
+            media_type_object = {}
+            media_type_object['schema'] = schema if schema
+            media_type_object['example'] = example_to_doc if @example
+            doc['content'] = Swaggard.configuration.api_formats.each_with_object({}) do |format, content|
+              content["application/#{format}"] = media_type_object
+            end
+          end
+
           if @headers.any?
             doc['headers'] = Hash[@headers.map { |header| [header.name, header.to_doc] }]
           end
@@ -64,10 +71,10 @@ module Swaggard
       end
 
       def example_to_doc
-        Swaggard.configuration.api_formats.inject({}) do |examples, format|
-          examples.merge!("application/#{format}" => { '$ref' => @example })
-
-          examples
+        if File.exist?(@example)
+          JSON.parse(File.read(@example))
+        else
+          { '$ref' => @example }
         end
       end
 
@@ -100,7 +107,7 @@ module Swaggard
           if PRIMITIVE_TYPES.include?(@response_class)
             { 'type' => @response_class }
           else
-            { '$ref' => "#/definitions/#@response_class" }
+            { '$ref' => "#/components/schemas/#{Swaggard.ref_name(@response_class)}" }
           end
         end
       end

data/lib/swaggard/swagger/response_header.rb

@@ -10,7 +10,7 @@ module Swaggard
       def to_doc
         {
           'description' => @description,
-          'type'        => @type,
+          'schema'      => { 'type' => @type },
         }
       end
 

data/lib/swaggard/swagger/type.rb

@@ -46,9 +46,9 @@ module Swaggard
         if basic_type?
           BASIC_TYPES[@name.downcase].dup
         elsif custom_type?
-          Swaggard.configuration.custom_types[@name].dup
+          { '$ref' => "#/components/schemas/#{Swaggard.ref_name(@name)}" }
         else
-          { '$ref' => "#/definitions/#{name}" }
+          { '$ref' => "#/components/schemas/#{Swaggard.ref_name(name)}" }
         end
       end
     end

data/lib/swaggard/version.rb

@@ -1,3 +1,3 @@
 module Swaggard
-  VERSION = '2.0.0'
+  VERSION = '4.0.0'
 end

data/lib/swaggard.rb

@@ -41,12 +41,20 @@ module Swaggard
       ::YARD::Tags::Library.define_tag('Ignore inherited attributes', :ignore_inherited)
     end
 
+    # Sanitize a name for use as an OpenAPI component key and $ref fragment.
+    # Keys must match ^[a-zA-Z0-9\.\-_]+$ per the OAS 3.1 spec.
+    def ref_name(name)
+      name.to_s.gsub('::', '.').gsub('#', '_')
+    end
+
     def get_doc(host = nil)
       load!
 
       doc = @api.to_doc
 
-      doc['host'] = host if doc['host'].blank? && host
+      if host && configuration.host.blank?
+        doc['servers'] = [{ 'url' => "#{configuration.schemes.first}://#{host}#{configuration.api_base_path}" }]
+      end
 
       doc
     end

data/spec/fixtures/api.json

@@ -1 +1 @@
-{"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":{}}
+{"openapi":"3.1.0","info":{"version":"0.1","title":"","description":"","contact":{"name":""},"license":{"name":""}},"servers":[{"url":"https://localhost:3000/"}],"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":"","parameters":[],"responses":{"default":{"description":"successful operation"}}}},"/pets":{"get":{"tags":["pets"],"operationId":"index","summary":"return a list of Pets","description":"","parameters":[],"responses":{"default":{"description":"successful operation"}}}},"/pets/{id}":{"get":{"tags":["pets"],"operationId":"show","summary":"return a Pet","description":"","parameters":[{"name":"id","in":"path","required":true,"description":"Scope response to id","schema":{"type":"string"}},{"name":"id","in":"query","required":false,"description":"The ID for the Pet","schema":{"type":"integer","format":"int32"}}],"responses":{"default":{"description":"successful operation"}}}}}}

data/spec/fixtures/dummy/config/application.rb

@@ -1,5 +1,4 @@
 require 'action_controller/railtie'
-require 'sprockets/railtie'
 
 # Load Swaggard
 require File.expand_path('../../../../../lib/swaggard', __FILE__)