swaggard 2.0.0 → 4.0.1

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)
@@ -64,7 +64,11 @@ module Swaggard
           def to_doc
             result = @type.to_doc
             result['description'] = @description if @description
-            result['enum'] = @options if @options.present?
+            if @options.present? && @type.is_array?
+              result['items']['enum'] = @options
+            elsif @options.present?
+              result['enum'] = @options
+            end
             result
           end
 
@@ -74,7 +78,6 @@ module Swaggard
           def parse(string)
             string.gsub!("\n", ' ')
             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(',') : []
 

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)
@@ -17,15 +26,12 @@ module Swaggard
         # Example: [Integer]   media[media_type_id]                          ID of the desired media type.
         def parse(string)
           data_type, name, required, description = string.match(/\A\[(\w*)\]\s*([\w\[\]]*)(\(required\))?\s*(.*)\Z/).captures
-          allow_multiple = name.gsub!('[]', '')
 
           @name = name
           @description = description
           @data_type = data_type.downcase
           @is_required = required.present?
-          @allow_multiple = allow_multiple.present?
         end
-
       end
     end
   end

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

@@ -11,14 +11,11 @@ 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,26 +11,30 @@ module Swaggard
         end
 
         def to_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)
+          schema = @type.to_doc
+
+          if @options.present? && @type.is_array?
+            schema['items']['enum'] = @options
+          elsif @options.present?
+            schema['enum'] = @options
           end
+
+          {
+            'name'        => @name,
+            'in'          => @in,
+            'required'    => @is_required,
+            'description' => description,
+            'schema'      => schema
+          }
         end
 
         private
 
         # 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!           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, 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(',') : []
@@ -39,7 +43,6 @@ module Swaggard
           @description = description
           @type = Parsers::Type.run(data_type)
           @is_required = required.present?
-          @allow_multiple = allow_multiple.present?
           @options = options
         end
       end

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
 
@@ -21,7 +21,6 @@ module Swaggard
       # 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(',') : []
@@ -29,7 +28,6 @@ module Swaggard
         @name = name
         @description = description
         @type = data_type
-        @allow_multiple = allow_multiple.present?
         @options = options
       end
     end

data/lib/swaggard/swagger/type.rb

@@ -24,6 +24,10 @@ module Swaggard
         @is_array = is_array
       end
 
+      def is_array?
+        @is_array
+      end
+
       def to_doc
         if @is_array
           { 'type' => 'array', 'items' => type_tag_and_name }
@@ -46,9 +50,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.1'
 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,111 @@
-{"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"
+            }
+          },
+          {
+            "name": "status",
+            "in": "query",
+            "required": false,
+            "description": "! [available, pending, sold] The status of the Pet",
+            "schema": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          }
+        ],
+        "responses": {
+          "default": {
+            "description": "successful operation"
+          }
+        }
+      }
+    }
+  }
+}

data/spec/fixtures/dummy/app/controllers/pets_controller.rb

@@ -9,6 +9,7 @@ class PetsController < ApplicationController
   # return a Pet
   #
   # @query_parameter [Integer] id The ID for the Pet
+  # @query_parameter [Array<String>] status! [available, pending, sold] The status of the Pet
   def show
   end
 

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__)