[feat] ApiObj.all_params

zhandao · zhandao · commit 48d98e782607 · 2024-02-26T17:23:03.000+08:00
diff --git a/README.md b/README.md
@@ -381,6 +381,7 @@
   body_ref      # 2. it links sepcified RefObjs (by component keys) to the body.
   body, body!   # 3. alias of request_body
   form, form!   # 4. to define a multipart/form-data request_body
+  json, json!   # 5. to define a application/json request_body
   data          # 5. to define [a] property in the form-data request_body
   ```
   Bang methods(!) means the specified media-type body is required.
@@ -422,6 +423,7 @@
          name!: String,
       password: { type: String, pattern: /[0-9]{6,10}/ },
   }
+  json data: { name!: String }
 
   # Part 5
   # ** Method Signature
diff --git a/README_zh.md b/README_zh.md
@@ -722,9 +722,9 @@
 
 ### Trick5 - Auto Generate index/show Actions's Response-Types Based on DB Schema
 
-  Use method `load_schema` in `api_dry`.
+  ~~Use method `load_schema` in `api_dry`.~~
 
-  See this [file](documentation/examples/auto_gen_doc.rb#L51) for uasge information.
+  ~~See this [file](documentation/examples/auto_gen_doc.rb#L51) for uasge information.~~
 
 ### Trick6 - Combined Schema (one_of / all_of / any_of / not)
 
diff --git a/lib/oas_objs/media_type_obj.rb b/lib/oas_objs/media_type_obj.rb
@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-require 'oas_objs/schema_obj'
-require 'oas_objs/example_obj'
+require "oas_objs/schema_obj"
+require "oas_objs/example_obj"
 
 module OpenApi
   module DSL
@@ -35,30 +35,30 @@ def process
       def media_type_mapping(media_type)
         return media_type if media_type.is_a? String
         case media_type
-        when :app then   'application/*'
-        when :json then  'application/json'
-        when :xml then   'application/xml'
-        when :xwww then  'application/x-www-form-urlencoded'
-        when :pdf then   'application/pdf'
-        when :zip then   'application/zip'
-        when :gzip then  'application/gzip'
-        when :doc then   'application/msword'
-        when :docx then  'application/application/vnd.openxmlformats-officedocument.wordprocessingml.document'
-        when :xls then   'application/vnd.ms-excel'
-        when :xlsx then  'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
-        when :ppt then   'application/vnd.ms-powerpoint'
-        when :pptx then  'application/vnd.openxmlformats-officedocument.presentationml.presentation'
-        when :form then  'multipart/form-data'; when :form_data then 'multipart/form-data'
-        when :text then  'text/*'
-        when :plain then 'text/plain then charset=utf-8'
-        when :html then  'text/html'
-        when :csv then   'text/csv'
-        when :image then 'image/*'
-        when :png then   'image/png'
-        when :jpeg then  'image/jpeg'
-        when :gif then   'image/gif'
-        when :audio then 'audio/*'
-        when :video then 'video/*'
+        when :app then   "application/*"
+        when :json then  "application/json"
+        when :xml then   "application/xml"
+        when :xwww then  "application/x-www-form-urlencoded"
+        when :pdf then   "application/pdf"
+        when :zip then   "application/zip"
+        when :gzip then  "application/gzip"
+        when :doc then   "application/msword"
+        when :docx then  "application/application/vnd.openxmlformats-officedocument.wordprocessingml.document"
+        when :xls then   "application/vnd.ms-excel"
+        when :xlsx then  "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
+        when :ppt then   "application/vnd.ms-powerpoint"
+        when :pptx then  "application/vnd.openxmlformats-officedocument.presentationml.presentation"
+        when :form then  "multipart/form-data"; when :form_data then "multipart/form-data"
+        when :text then  "text/*"
+        when :plain then "text/plain then charset=utf-8"
+        when :html then  "text/html"
+        when :csv then   "text/csv"
+        when :image then "image/*"
+        when :png then   "image/png"
+        when :jpeg then  "image/jpeg"
+        when :gif then   "image/gif"
+        when :audio then "audio/*"
+        when :video then "video/*"
         else             nil
         end
       end
@@ -95,4 +95,4 @@ def media_type_mapping(media_type)
       }
     }
   }
-}
+}
diff --git a/lib/oas_objs/request_body_obj.rb b/lib/oas_objs/request_body_obj.rb
@@ -14,7 +14,7 @@ class RequestBodyObj < Hash
 
       def initialize(required, desc)
         self.media_types = [ ]
-        self.processed   = { required: required['req'].present?, description: desc }
+        self.processed   = { required: required.to_s[/req/].present?, description: desc }
       end
 
       def absorb(media_type, hash)
diff --git a/lib/open_api/dsl/api.rb b/lib/open_api/dsl/api.rb
@@ -7,122 +7,129 @@ module DSL
     class Api < Hash
       include DSL::Helpers
 
+      attr_accessor :_all_params
       attr_accessor :action_path, :dry_skip, :dry_only, :dry_blocks, :dryed, :param_order
 
-      def initialize(action_path = '', summary: nil, tags: [ ], id: nil)
+      def initialize(action_path = "", summary: nil, tags: [ ], id: nil)
         self.action_path = action_path
         self.dry_blocks  = [ ]
-        self.merge!(summary: summary, operationId: id, tags: tags, description: '', parameters: [ ],
-                    requestBody: nil, responses: { }, callbacks: { }, links: { }, security: [ ], servers: [ ])
+        self._all_params = { }
+        self.merge!(
+          summary: summary, operationId: id, tags: tags, description: "", parameters: [ ],
+          requestBody: nil, responses: { }, callbacks: { }, links: { }, security: [ ], servers: [ ]
+        )
       end
 
       def this_api_is_invalid!(*)
         self[:deprecated] = true
       end
-
       alias this_api_is_expired!      this_api_is_invalid!
       alias this_api_is_unused!       this_api_is_invalid!
       alias this_api_is_under_repair! this_api_is_invalid!
 
-      def desc desc
+      def desc(desc)
         self[:description] = desc
       end
-
       alias description desc
 
-      def dry only: nil, skip: nil, none: false
+      def dry(only: nil, skip: nil, none: false)
         return if dry_blocks.blank? || dryed
-        self.dry_skip = skip && Array(skip)
-        self.dry_only = none ? [:none] : only && Array(only)
+
+        self.dry_skip = Array(skip).compact.presence
+        self.dry_only = none ? [:none] : Array(only).compact.presence
         dry_blocks.each { |blk| instance_eval(&blk) }
         self.dry_skip = self.dry_only = nil
         self.dryed = true
       end
 
-      def param param_type, name, type, required, schema = { }
+      def param(param_type, name, type, required, schema = { })
         return if dry_skip&.include?(name) || dry_only&.exclude?(name)
+        return unless (schema_obj = process_schema_input(type, schema, name))
 
-        return unless schema = process_schema_input(type, schema, name)
-        param_obj = ParamObj.new(name, param_type, type, required, schema)
-        # The definition of the same name parameter will be overwritten
-        index = self[:parameters].map(&:name).index(param_obj.name)
-        index ? self[:parameters][index] = param_obj : self[:parameters] << param_obj
+        _all_params[name] = schema.is_a?(Hash) ? schema.merge(type:) : { type: } unless param_type["header"]
+        override_or_append_to_parameters(
+          ParamObj.new(name, param_type, type, required, schema_obj)
+        )
       end
-
       alias parameter param
 
+      # @!method query(name, type = nil, **schema)
+      # @!method query!(name, type = nil, **schema)
+      # @!method in_query(**params)
+      # @!method in_query!(**params)
       %i[ header header! path path! query query! cookie cookie! ].each do |param_type|
-        define_method param_type do |name, type = nil, **schema|
-          param param_type, name, type, (param_type['!'] ? :req : :opt), schema
+        define_method(param_type) do |name, type = nil, **schema|
+          param param_type, name, type, required?(param_type), schema
         end
 
-        define_method "in_#{param_type}" do |params|
+        define_method("in_#{param_type}") do |params|
           params.each_pair do |param_name, schema|
-            param param_type, param_name, nil, (param_type['!'] || param_name['!'] ? :req : :opt), schema
+            param param_type, param_name, nil, required?(param_type, param_name), schema
           end
         end
       end
 
-      def param_ref component_key, *keys
+      def param_ref(component_key, *keys)
         self[:parameters] += [component_key, *keys].map { |key| RefObj.new(:parameter, key) }
       end
 
       # options: `exp_params` and `examples`
-      def request_body required, media_type, data: { }, desc: '', **options
-        (self[:requestBody] ||= RequestBodyObj.new(required, desc)).absorb(media_type, { data: data , **options })
+      def request_body(required, media_type, data: { }, desc: "", **options)
+        self[:requestBody] ||= RequestBodyObj.new(required, desc)
+        self[:requestBody].absorb(media_type, { data:, **options })
+        _all_params.merge!(data)
       end
 
-      def body_ref component_key
-        self[:requestBody] = RefObj.new(:requestBody, component_key)
-      end
+      def body(media_type, data: { }, **) = request_body(:optional, media_type, data:, **)
+      def body!(media_type, data: { }, **) = request_body(:required, media_type, data:, **)
 
-      %i[ body body! ].each do |method|
-        define_method method do |media_type, data: { }, **options|
-          request_body (method['!'] ? :req : :opt), media_type, data: data, **options
-        end
-      end
-
-      def form data:, **options
-        body :form, data: data, **options
-      end
+      def json(data:, **) = body(:json, data:, **)
+      def json!(data:, **) = body!(:json, data:, **)
+      def form(data:, **) = body(:form, data:, **)
+      def form!(data:, **) = body!(:form, data:, **)
 
-      def form! data:, **options
-        body! :form, data: data, **options
-      end
-
-      def data name, type = nil, schema = { }
+      def data(name, type = nil, schema = { })
         schema[:type] = type if type.present?
         form data: { name => schema }
       end
 
-      def response code, desc, media_type = nil, headers: { }, data: { }, **options
-        (self[:responses][code.to_s] ||= ResponseObj.new(desc)).absorb(desc, media_type, headers: headers, data: data, **options)
+      def body_ref(component_key)
+        self[:requestBody] = RefObj.new(:requestBody, component_key)
+      end
+
+      def response(code, desc, media_type = nil, headers: { }, data: { }, **)
+        self[:responses][code.to_s] ||= ResponseObj.new(desc)
+        self[:responses][code.to_s].absorb(desc, media_type, headers:, data:, **)
       end
 
       alias_method :resp,  :response
       alias_method :error, :response
 
-      def response_ref code_and_compkey # = { }
-        code_and_compkey.each { |code, component_key| self[:responses][code.to_s] = RefObj.new(:response, component_key) }
+      def response_ref(code_and_compkey) # = { }
+        code_and_compkey.each do |code, component_key|
+          self[:responses][code.to_s] = RefObj.new(:response, component_key)
+        end
       end
 
-      def security_require scheme_name, scopes: [ ]
+      def security_require(scheme_name, scopes: [ ])
         self[:security] << { scheme_name => scopes }
       end
 
       alias security  security_require
       alias auth      security_require
       alias auth_with security_require
 
-      def callback event_name, http_method, callback_url, &block
-        self[:callbacks].deep_merge! CallbackObj.new(event_name, http_method, callback_url, &block).process
+      def callback(event_name, http_method, callback_url, &block)
+        self[:callbacks].deep_merge!(
+          CallbackObj.new(event_name, http_method, callback_url, &block).process
+        )
       end
 
-      def server url, desc: ''
+      def server(url, desc: "")
         self[:servers] << { url: url, description: desc }
       end
 
-      def param_examples exp_params = :all, examples_hash
+      def param_examples(exp_params = :all, examples_hash)
         exp_params = self[:parameters].map(&:name) if exp_params == :all
         self[:examples] = ExampleObj.new(examples_hash, exp_params, multiple: true).process
       end
@@ -135,10 +142,31 @@ def run_dsl(dry: false, &block)
 
         self[:parameters].map!(&:process)
         self[:requestBody] = self[:requestBody].try(:process)
-        self[:responses].each { |code, response| self[:responses][code] = response.process }
-        self[:responses] = self[:responses].sort.to_h
+        self[:responses] = self[:responses].transform_values(&:process).sort.to_h
         self.delete_if { |_, v| v.blank? }
       end
+
+      def all_params
+        _all_params.transform_values do |t|
+          if t.is_a?(Hash)
+            t.key?(:type) ? t.merge!(type: t[:type].to_s.underscore) : { type: t }
+          else
+            { type: t.to_s.underscore }
+          end
+        end
+      end
+
+      private
+
+        def override_or_append_to_parameters(param_obj)
+          # The definition of the same name parameter will be override.
+          index = self[:parameters].map(&:name).index(param_obj.name)
+          index ? self[:parameters][index] = param_obj : self[:parameters] << param_obj
+        end
+
+        def required?(*passed)
+          passed.join["!"] ? :required : :optional
+        end
     end
   end
 end
diff --git a/lib/open_api/dsl/components.rb b/lib/open_api/dsl/components.rb
@@ -12,7 +12,7 @@ def initialize
       end
 
       def schema component_key, type = nil, **schema
-        return unless schema = process_schema_input(type, schema, component_key, model: component_key)
+        return unless (schema = process_schema_input(type, schema, component_key))
         self[:schemas][component_key.to_s.to_sym] = schema.process
       end
 
@@ -25,7 +25,7 @@ def example component_key, examples_hash
       arrow_enable :example
 
       def param component_key, param_type, name, type, required, schema = { }
-        return unless schema = process_schema_input(type, schema, name)
+        return unless (schema = process_schema_input(type, schema, name))
         self[:parameters][component_key] = ParamObj.new(name, param_type, type, required, schema).process
       end
 
diff --git a/lib/open_api/dsl/helpers.rb b/lib/open_api/dsl/helpers.rb
@@ -15,26 +15,20 @@ module DSL
     module Helpers
       extend ActiveSupport::Concern
 
-      def load_schema(model) # TODO: test
-        return unless Config.model_base && model.try(:superclass) == Config.model_base
-        model.columns.map do |column|
-            type = column.sql_type_metadata.type.to_s.camelize
-            type = 'DateTime' if type == 'Datetime'
-            [ column.name.to_sym, Object.const_get(type) ]
-          end.to_h rescue ''
-      end
-
       def _combined_schema(one_of: nil, all_of: nil, any_of: nil, not: nil, **other)
         input = (_not = binding.local_variable_get(:not)) || one_of || all_of || any_of
         CombinedSchema.new(one_of: one_of, all_of: all_of, any_of: any_of, not: _not) if input
       end
 
-      def process_schema_input(schema_type, schema, name, model: nil)
-        schema = { type: schema } unless schema.is_a?(Hash)
+      def process_schema_input(schema_type, schema, name)
+        if schema.is_a?(Hash)
+          schema[:type] ||= schema_type
+        else
+          schema = { type: schema }
+        end
         combined_schema = _combined_schema(**schema)
-        type = schema[:type] ||= schema_type
-        return Tip.param_no_type(name) if type.nil? && combined_schema.nil?
-        combined_schema || SchemaObj.new(type, load_schema(model) || schema)
+        return Tip.param_no_type(name) if schema[:type].nil? && combined_schema.nil?
+        combined_schema || SchemaObj.new(schema[:type], schema)
       end
 
       # Arrow Writing:
diff --git a/lib/open_api/version.rb b/lib/open_api/version.rb
@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OpenApi
-  VERSION = '2.1.5'
+  VERSION = "2.2.0"
 end
diff --git a/zero-rails_openapi.gemspec b/zero-rails_openapi.gemspec
@@ -21,7 +21,7 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
-  spec.required_ruby_version = '>= 2.3.0'
+  spec.required_ruby_version = '>= 3.0.0'
 
   spec.add_development_dependency 'bundler'
   spec.add_development_dependency 'rake'
