Initial support for openapi3 requestBody

Author: blake

lib/grape-swagger/openapi_3/doc_methods/parse_request_body.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module GrapeSwagger
+  module DocMethods
+    class ParseRequestBody
+      class << self
+        def call(param, settings, path, route, _definitions)
+          method = route.request_method
+          additional_documentation = settings.fetch(:documentation, {})
+          settings.merge!(additional_documentation)
+          data_type = DataType.call(settings)
+
+          value_type = settings.merge(data_type: data_type, path: path, param_name: param, method: method)
+
+          type = param_type(value_type)
+          return nil if type.nil?
+
+          # required properties
+          @parsed_param = {
+            in:   type,
+            name: settings[:full_name] || param
+          }
+
+          # optional properties
+          document_description(settings)
+          document_type_and_format(settings, data_type)
+          document_array_param(value_type, definitions) if value_type[:is_array]
+          document_default_value(settings) unless value_type[:is_array]
+          document_range_values(settings) unless value_type[:is_array]
+          document_required(settings)
+
+          @parsed_param
+        end
+
+        private
+
+        def document_description(settings)
+          description = settings[:desc] || settings[:description]
+          @parsed_param[:description] = description if description
+        end
+
+        def document_required(settings)
+          @parsed_param[:required] = settings[:required] || false
+          @parsed_param[:required] = true if @parsed_param[:in] == 'path'
+        end
+
+        def document_range_values(settings)
+          values               = settings[:values] || nil
+          enum_or_range_values = parse_enum_or_range_values(values)
+          @parsed_param.merge!(enum_or_range_values) if enum_or_range_values
+        end
+
+        def document_default_value(settings)
+          @parsed_param[:default] = settings[:default] if settings[:default].present?
+        end
+
+        def document_type_and_format(settings, data_type)
+          if DataType.primitive?(data_type)
+            data = DataType.mapping(data_type)
+            @parsed_param[:type], @parsed_param[:format] = data
+          else
+            @parsed_param[:type] = data_type
+          end
+          @parsed_param[:format] = settings[:format] if settings[:format].present?
+        end
+
+        def document_array_param(value_type, definitions)
+          if value_type[:documentation].present?
+            param_type = value_type[:documentation][:param_type]
+            doc_type = value_type[:documentation][:type]
+            type = DataType.mapping(doc_type) if doc_type && !DataType.request_primitive?(doc_type)
+            collection_format = value_type[:documentation][:collectionFormat]
+          end
+
+          param_type ||= value_type[:param_type]
+
+          array_items = {}
+          if definitions[value_type[:data_type]]
+            array_items['$ref'] = "#/definitions/#{@parsed_param[:type]}"
+          else
+            array_items[:type] = type || @parsed_param[:type] == 'array' ? 'string' : @parsed_param[:type]
+          end
+          array_items[:format] = @parsed_param.delete(:format) if @parsed_param[:format]
+
+          values = value_type[:values] || nil
+          enum_or_range_values = parse_enum_or_range_values(values)
+          array_items.merge!(enum_or_range_values) if enum_or_range_values
+
+          array_items[:default] = value_type[:default] if value_type[:default].present?
+
+          @parsed_param[:in] = param_type || 'formData'
+          @parsed_param[:items] = array_items
+          @parsed_param[:type] = 'array'
+          @parsed_param[:collectionFormat] = collection_format if DataType.collections.include?(collection_format)
+        end
+
+        def param_type(value_type)
+          if value_type[:path].include?("{#{value_type[:param_name]}}")
+            nil
+          elsif %w[POST PUT PATCH].include?(value_type[:method])
+            DataType.request_primitive?(value_type[:data_type]) ? 'formData' : 'body'
+          end
+        end
+
+        def parse_enum_or_range_values(values)
+          case values
+          when Proc
+            parse_enum_or_range_values(values.call) if values.parameters.empty?
+          when Range
+            parse_range_values(values) if values.first.is_a?(Integer)
+          else
+            { enum: values } if values
+          end
+        end
+
+        def parse_range_values(values)
+          { minimum: values.first, maximum: values.last }
+        end
+      end
+    end
+  end
+end

lib/grape-swagger/openapi_3/endpoint.rb

@@ -3,6 +3,7 @@
 require 'active_support'
 require 'active_support/core_ext/string/inflections'
 require 'grape-swagger/endpoint/params_parser'
+require 'grape-swagger/openapi_3/doc_methods/parse_request_body'
 
 module Grape
   class Endpoint
@@ -116,10 +117,13 @@ def method_object(route, options, path)
       method = {}
       method[:summary]     = summary_object(route)
       method[:description] = description_object(route)
-      # method[:consumes]    = consumes_object(route, options[:format])
       method[:parameters]  = params_object(route, options, path)
       method[:security]    = security_object(route)
+      if %w[POST PUT PATCH].include?(route.request_method)
+        method[:requestBody] = response_body_object(route, options, path)
+      end
 
+      # method[:consumes]    = consumes_object(route, options[:format])
       produces = produces_object(route, options[:produces] || options[:format])
 
       method[:responses]   = response_object(route, produces)
@@ -196,6 +200,36 @@ def params_object(route, options, path)
       parameters
     end
 
+    def response_body_object(route, options, path)
+      parameters = partition_params(route, options).map do |param, value|
+        value = { required: false }.merge(value) if value.is_a?(Hash)
+        _, value = default_type([[param, value]]).first if value == ''
+        if value[:type]
+          expose_params(value[:type])
+        elsif value[:documentation]
+          expose_params(value[:documentation][:type])
+        end
+
+        GrapeSwagger::DocMethods::ParseRequestBody.call(param, value, path, route, @definitions)
+      end.flatten
+
+      parameters = {
+        'content' => parameters.group_by { |p| p[:in] }.map do |_k, v|
+          required_values = v.select { |param| param[:required] }
+          [
+            'application/x-www-form-urlencoded',
+            { 'schema' => {
+              'type' => 'object',
+              'required' => required_values.map { |required| required[:name] },
+              'properties' => v.map { |value| [value[:name], value.except(:name, :in, :required)] }.to_h
+            } }
+          ]
+        end.to_h
+      }
+
+      parameters
+    end
+
     def response_object(route, content_types)
       codes = http_codes_from_route(route)
       codes.map! { |x| x.is_a?(Array) ? { code: x[0], message: x[1], model: x[2], examples: x[3], headers: x[4] } : x }

spec/openapi_3/params_hash_spec.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'Group Params as Hash' do
+  def app
+    Class.new(Grape::API) do
+      format :json
+
+      params do
+        requires :required_group, type: Hash do
+          requires :required_param_1
+          requires :required_param_2
+        end
+      end
+      post '/use_groups' do
+        { 'declared_params' => declared(params) }
+      end
+
+      params do
+        requires :typed_group, type: Hash do
+          requires :id, type: Integer, desc: 'integer given'
+          requires :name, type: String, desc: 'string given'
+          optional :email, type: String, desc: 'email given'
+          optional :others, type: Integer, values: [1, 2, 3]
+        end
+      end
+      post '/use_given_type' do
+        { 'declared_params' => declared(params) }
+      end
+
+      add_swagger_documentation openapi_version: '3.0'
+    end
+  end
+
+  describe 'grouped parameters' do
+    subject do
+      get '/swagger_doc/use_groups'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['paths']['/use_groups']['post']).to include('requestBody')
+      expect(subject['paths']['/use_groups']['post']['requestBody']['content']).to eql(
+        'application/x-www-form-urlencoded' => {
+          'schema' => {
+            'properties' => {
+              'required_group[required_param_1]' => { 'type' => 'string' },
+              'required_group[required_param_2]' => { 'type' => 'string' }
+            },
+            'required' => %w(required_group[required_param_1] required_group[required_param_2]),
+            'type' => 'object'
+          }
+        }
+      )
+    end
+  end
+
+  describe 'grouped parameters with given type' do
+    subject do
+      get '/swagger_doc/use_given_type'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['paths']['/use_given_type']['post']).to include('requestBody')
+      expect(subject['paths']['/use_given_type']['post']['requestBody']['content']).to eql(
+        'application/x-www-form-urlencoded' => {
+          'schema' => {
+            'properties' => {
+              'typed_group[email]' => { 'description' => 'email given', 'type' => 'string' },
+              'typed_group[id]' => { 'description' => 'integer given', 'format' => 'int32', 'type' => 'integer' },
+              'typed_group[name]' => { 'description' => 'string given', 'type' => 'string' },
+              'typed_group[others]' => { 'enum' => [1, 2, 3], 'format' => 'int32', 'type' => 'integer' }
+            },
+            'required' => ['typed_group[id]', 'typed_group[name]'],
+            'type' => 'object'
+          }
+        }
+      )
+    end
+  end
+end