zero-rails_openapi 1.3.3 → 1.4.0

data/lib/oas_objs/combined_schema.rb

@@ -0,0 +1,28 @@
+module OpenApi
+  module DSL
+    # https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/
+    # https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#schemaObject
+    class CombinedSchema < Hash
+      attr_accessor :processed
+
+      def initialize(combined_schema)
+        self.processed = { }
+
+        combined_schema.delete_if { |_, v| v.nil? }
+        @mode = combined_schema.keys.first.to_s.sub('_not', 'not').camelize(:lower).to_sym
+        @schemas = combined_schema.values.first
+      end
+
+      def process_for(param_name = nil, options = { desc_inside: false })
+        processed.tap do |it|
+          it[@mode] = @schemas.map do |schema|
+            type = schema.is_a?(Hash) ? schema[:type] : schema
+            schema = { } unless schema.is_a?(Hash)
+            SchemaObj.new(type, schema).process_for(param_name, options) end
+        end
+      end
+
+      alias process process_for
+    end
+  end
+end

data/lib/oas_objs/example_obj.rb

@@ -10,7 +10,7 @@ module OpenApi
       attr_accessor :processed, :examples_hash, :keys_of_value
 
       def initialize(examples_hash, keys_of_value = nil)
-        self.examples_hash  = examples_hash
+        self.examples_hash = examples_hash
         self.keys_of_value = keys_of_value
       end
 

data/lib/oas_objs/helpers.rb

@@ -1,6 +1,5 @@
 module OpenApi
   module Helpers
-
     # TODO: comment-block doc
     def truly_present?(obj)
       obj == false || obj.present?
@@ -23,11 +22,13 @@ module OpenApi
     end
 
     def to_processed(who)
+      return processed unless truly_present?(@assign)
+
       if who.is_a?(Symbol)
         send("#{who}=", @assign)
       else
         processed[who.to_sym] = @assign
-      end if truly_present?(@assign)
+      end
 
       processed
     end

data/lib/oas_objs/media_type_obj.rb

@@ -21,7 +21,7 @@ module OpenApi
       def process
         schema_processed = schema.process
         result = schema_processed.values.join.blank? ? { } : { schema: schema_processed }
-        result.merge!(examples: examples.process) unless examples.nil?
+        result[:examples] = examples.process unless examples.nil?
         media_type.nil? ? { } : { media_type => result }
       end
 

data/lib/oas_objs/param_obj.rb

@@ -7,19 +7,20 @@ module OpenApi
       include Helpers
 
       attr_accessor :processed, :schema
-      def initialize(name, param_type, type, required, schema_hash)
+
+      def initialize(name, param_type, type, required, schema)
         self.processed = {
             name: name,
             in: param_type,
-            required: required.to_s.match?(/req/),
+            required: required.to_s.match?(/req/)
         }
-        self.schema = SchemaObj.new(type, schema_hash)
-        merge! schema_hash
+        self.schema = schema.is_a?(CombinedSchema) ? schema : SchemaObj.new(type, schema)
+        merge! schema
       end
 
       def process
         assign(desc).to_processed 'description'
-        processed.tap { |it| it[:schema] = schema.process_for self.processed[:name] }
+        processed.tap { |it| it[:schema] = schema.process_for(processed[:name]) }
       end
 
       def desc

data/lib/oas_objs/response_obj.rb

@@ -21,7 +21,7 @@ module OpenApi
         processed
       end
 
-      def override type_hash
+      def override(type_hash)
         @hash[:type].merge!(type_hash)
         self.media_type = MediaTypeObj.new(@mt, @hash)
         self

data/lib/oas_objs/schema_obj.rb

@@ -34,7 +34,7 @@ module OpenApi
                {
                    pattern:    _pattern&.inspect&.delete('/'),
                    default:    _default.nil? ? nil : '_default',
-                   examples:   self[:examples].present? ? ExampleObj.new(self[:examples], self[:exp_by]).process : nil,
+                   examples:   self[:examples].present? ? ExampleObj.new(self[:examples], self[:exp_by]).process : nil
                },
                { as: _as, permit: _permit, not_permit: _npermit, req_if: _req_if, opt_if: _opt_if }
         then_merge!
@@ -75,14 +75,17 @@ module OpenApi
       end
 
       def processed_type(type = self.type)
-        t = type.class.in?([Hash, Array, Symbol]) ? type : "#{type}".downcase
+        t = type.class.in?([Hash, Array, Symbol]) ? type : type.to_s.downcase
         if t.is_a? Hash
-          # For supporting writing:
+          # For supporting this:
           #   form 'desc', data: {
           #     id!: { type: Integer, enum: 0..5, desc: 'user id' }
           # }
-          if t.key? :type
-            SchemaObj.new(t[:type], t).process_for @prop_name, desc_inside: true
+          if t.key?(:type)
+            SchemaObj.new(t[:type], t).process_for(@prop_name, desc_inside: true)
+          # For supporting combined schema in nested schema.
+          elsif (t.keys & %i[ one_of any_of all_of not ]).present?
+            CombinedSchema.new(t).process_for(@prop_name, desc_inside: true)
           else
             recursive_obj_type t
           end
@@ -104,7 +107,7 @@ module OpenApi
       end
 
       def recursive_obj_type(t) # DSL use { prop_name: prop_type } to represent object structure
-        return processed_type(t) if !t.is_a?(Hash) || t.key?(:type)
+        return processed_type(t) if !t.is_a?(Hash) || (t.keys & %i[ type one_of any_of all_of not ]).present?
 
         _schema = {
             type: 'object',
@@ -116,7 +119,7 @@ module OpenApi
           _schema[:required] << "#{prop_name}".delete('!') if prop_name['!']
           _schema[:properties]["#{prop_name}".delete('!').to_sym] = recursive_obj_type prop_type
         end
-        _schema.keep_if &value_present
+        _schema.keep_if(&value_present)
       end
 
       def recursive_array_type(t)
@@ -185,7 +188,7 @@ module OpenApi
       def recognize_is_options_in(name)
         # identify whether `is` patterns matched the name, if so, generate `is`.
         Config.is_options.each do |pattern|
-          self._is = pattern or break if name.match? /#{pattern}/
+          self._is = pattern or break if name.match?(/#{pattern}/)
         end if _is.nil?
       end
 

data/lib/open_api.rb

@@ -5,4 +5,12 @@ require "open_api/dsl"
 
 module OpenApi
   include Generator
+
+  cattr_accessor :paths_index do
+    { }
+  end
+
+  cattr_accessor :docs do
+    { }
+  end
 end

data/lib/open_api/config.rb

@@ -14,12 +14,16 @@ module OpenApi
       true
     end
 
+    cattr_accessor :rails_routes_file do
+      nil
+    end
+
     # Everything about OAS3 is on https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md
     # Getting started: https://swagger.io/docs/specification/basic-structure/
-    cattr_accessor :register_docs do
+    cattr_accessor :open_api_docs do
       {
       #     # [REQUIRED] At least one doc.
-      #     zero_rails_api: {
+      #     zero_rails: {
       #         # [REQUIRED] ZRO will scan all the descendants of the root_controller, and then generate their docs.
       #         root_controller: ApplicationController,
       #
@@ -36,7 +40,7 @@ module OpenApi
     end
 
     cattr_accessor :is_options do
-      %w[ email phone password uuid uri url time date ]
+      %w[ email phone mobile password uuid uri url time date ]
     end
 
     cattr_accessor :dft_file_format do
@@ -52,58 +56,11 @@ module OpenApi
     end
 
     cattr_accessor :jbuilder_templates do
-      {
-          index: (
-          <<~FILE
-            # *** Generated by ZRO [ please make sure that you have checked this file ] ***
-            json.partial! 'api/base', total: @data.size
-            
-            json.data do
-              # @data = @data.page(@_page).per(@_rows) if @_page || @_rows
-              # json.array! @data do |datum|
-              json.array! @data.page(@_page).per(@_rows) do |datum|
-                json.(datum, *datum.show_attrs) if datum.present?
-              end
-            end
-          FILE
-          ),
-
-          show: (
-          <<~FILE
-            # *** Generated by ZRO [ please make sure that you have checked this file ] ***
-            json.partial! 'api/base', total: 1
-            
-            json.data do
-              json.array! [ @data ] do |datum|
-                json.(datum, *datum.show_attrs) if datum.present?
-              end
-            end
-          FILE
-          ),
-
-          success: (
-          <<~FILE
-            # *** Generated by ZRO [ please make sure that you have checked this file ] ***
-            json.partial! 'api/success'
-          FILE
-          ),
-
-          success_or_not: (
-          <<~FILE
-            # *** Generated by ZRO [ please make sure that you have checked this file ] ***
-            unless @status
-              # @_code, @_msg = @error_info.present? ? @error_info : ApiError.action_failed.info
-            end
-            
-            json.partial! 'api/base', total: 0
-            json.data ''
-          FILE
-          ),
-      }
+      { }
     end
 
     def self.docs
-      register_docs
+      open_api_docs
     end
   end
 end

data/lib/open_api/config_dsl.rb

@@ -4,27 +4,45 @@ module OpenApi
       base.class_eval do
         module_function
 
-        def api name, root_controller:
+        def open_api name, root_controller:
           @api = name
-          register_docs[name] = { root_controller: root_controller }
+          open_api_docs[name] = { root_controller: root_controller }
         end
 
         def info version:, title:, **addition
-          register_docs[@api].merge! version: version, title: title, **addition
+          open_api_docs[@api][:info] = { version: version, title: title, **addition }
         end
 
         def server url, desc: ''
-          (register_docs[@api][:servers] ||= [ ]) << { url: url, description: desc }
+          (open_api_docs[@api][:servers] ||= [ ]) << { url: url, description: desc }
         end
 
-        def security requirement
-          (register_docs[@api][:global_security] ||= [ ]) << requirement
+        def security_scheme scheme_name, other_info# = { }
+          other_info[:description] = other_info.delete(:desc) if other_info.key?(:desc)
+          (open_api_docs[@api][:security_schemes] ||= { })[scheme_name] = other_info
         end
 
-        alias_method :security_require, :security
+        def base_auth scheme_name, other_info = { }
+          security_scheme scheme_name, { type: 'http', scheme: 'basic' }.merge(other_info)
+        end
+
+        def bearer_auth scheme_name, format = 'JWT', other_info = { }
+          security_scheme scheme_name, { type: 'http', scheme: 'bearer', bearerFormat: format }.merge(other_info)
+        end
+
+        def api_key scheme_name, field:, in:, **other_info
+          _in = binding.local_variable_get(:in)
+          security_scheme scheme_name, { type: 'apiKey', name: field, in: _in }.merge(other_info)
+        end
+
+        def global_security_require scheme_name, scopes: [ ]
+          (open_api_docs[@api][:global_security] ||= [ ]) << { scheme_name => scopes }
+        end
 
-        def security_scheme scheme_name, schema# = { }
-          (register_docs[@api][:global_security_schemes] ||= { }).merge! scheme_name => schema
+        class << self
+          alias global_security global_security_require
+          alias global_auth     global_security_require
+          alias auth_scheme security_scheme
         end
       end
     end

data/lib/open_api/dsl.rb

@@ -30,40 +30,35 @@ module OpenApi
         current_ctrl._process_objs
       end
 
-      def open_api action, summary = '', builder: nil, skip: [ ], use: [ ], &block
+      def api action, summary = '', http: nil, builder: nil, skip: [ ], use: [ ], &block
         apis_tag if @_ctrl_infos.nil?
-
         # select the routing info (corresponding to the current method) from routing list.
         action_path = "#{@_ctrl_path ||= controller_path}##{action}"
-        routes_info = ctrl_routes_list&.select { |api| api[:action_path].match? /^#{action_path}$/ }&.first
+        routes_info = ctrl_routes_list&.select { |api| api[:action_path].match?(/^#{action_path}$/) }&.first
         pp "[ZRO Warning] Routing mapping failed: #{@_ctrl_path}##{action}" and return if routes_info.nil?
-        Generator.generate_builder_file(action_path, builder) if builder.present?
+        Generator.generate_builder_file(action_path, builder)
 
-        # structural { #path: { #http_method:{ } } }, for pushing into Paths Object.
-        path = (@_api_infos ||= { })[routes_info[:path]] ||= { }
-        current_api = path[routes_info[:http_verb]] =
-            ApiInfoObj.new(action_path, skip: Array(skip), use: Array(use))
-                .merge! description: '', summary: summary, operationId: action, tags: [@_apis_tag],
-                        parameters: [ ], requestBody: '',  responses: { },      security: [ ], servers: [ ]
+        api = ApiInfoObj.new(action_path, skip: Array(skip), use: Array(use))
+                        .merge! description: '', summary: summary, operationId: action, tags: [@_apis_tag],
+                                parameters: [ ], requestBody: '',  responses: { },      security: [ ], servers: [ ]
+        [action, :all].each { |blk_key| @_api_dry_blocks&.[](blk_key)&.each { |blk| api.instance_eval(&blk) } }
+        api.param_use = [ ] # `skip` and `use` only affect `api_dry`'s blocks
+        api.instance_eval(&block) if block_given?
+        api._process_objs
+        api.delete_if { |_, v| v.blank? }
 
-        current_api.tap do |api|
-          [action, :all].each do |key| # blocks_store_key
-            @_apis_blocks&.[](key)&.each { |blk| api.instance_eval(&blk) }
-          end
-          api.param_use = [ ] # skip 和 use 是对 dry 块而言的
-          api.instance_eval(&block) if block_given?
-          api._process_objs
-          api.delete_if { |_, v| v.blank? }
-        end
+        path = (@_api_infos ||= { })[routes_info[:path]] ||= { }
+        http_verbs = (http || routes_info[:http_verb]).split('|')
+        http_verbs.each { |verb| path[verb] = api }
       end
 
       # method could be symbol array, like: %i[ .. ]
       def api_dry action = :all, desc = '', &block
-        @_apis_blocks ||= { }
+        @_api_dry_blocks ||= { }
         if action.is_a? Array
-          action.each { |m| (@_apis_blocks[m.to_sym] ||= [ ]) << block }
+          action.each { |m| (@_api_dry_blocks[m.to_sym] ||= [ ]) << block }
         else
-          (@_apis_blocks[action.to_sym] ||= [ ]) << block
+          (@_api_dry_blocks[action.to_sym] ||= [ ]) << block
         end
       end
 

data/lib/open_api/dsl/api_info_obj.rb

@@ -30,7 +30,7 @@ module OpenApi
 
       def param param_type, name, type, required, schema_hash = { }
         return if param_skip.include?(name)
-        return if param_use.present? && !param_use.include?(name)
+        return if param_use.present? && param_use.exclude?(name)
 
         _t = nil
         schema_hash[:desc]  = _t if (_t = param_descs[name]).present?
@@ -38,16 +38,16 @@ module OpenApi
 
         param_obj = ParamObj.new(name, param_type, type, required, schema_hash)
         # The definition of the same name parameter will be overwritten
-        index = self[:parameters].map { |p| p.processed[:name] if p.is_a? ParamObj }.index name
+        index = self[:parameters].map { |p| p.processed[:name] if p.is_a?(ParamObj) }.index name
         index.present? ? self[:parameters][index] = param_obj : self[:parameters] << param_obj
       end
 
-      # Support this writing: (just like `form '', data: { }`)
+      # For supporting this: (just like `form '', data: { }` usage)
       #   do_query by: {
       #     :search_type => { type: String  },
       #         :export! => { type: Boolean }
       #   }
-      %i[header header! path path! query query! cookie cookie!].each do |param_type|
+      %i[ header header! path path! query query! cookie cookie! ].each do |param_type|
         define_method "do_#{param_type}" do |by:|
           by.each do |key, value|
             args = [ key.dup.to_s.delete('!').to_sym, value.delete(:type), value ]
@@ -56,7 +56,12 @@ module OpenApi
         end unless param_type.to_s['!']
       end
 
-      def _param_agent name, type, schema_hash = { }
+      def _param_agent name, type = nil, one_of: nil, all_of: nil, any_of: nil, not: nil, **schema_hash
+        (schema_hash = type) and (type = type.delete(:type)) if type.is_a?(Hash) && type.key?(:type)
+        type = schema_hash[:type] if type.nil?
+
+        combined_schema = one_of || all_of || any_of || (_not = binding.local_variable_get(:not))
+        schema_hash = CombinedSchema.new(one_of: one_of, all_of: all_of, any_of: any_of, _not: _not) if combined_schema
         param "#{@param_type}".delete('!'), name, type, (@param_type['!'] ? :req : :opt), schema_hash
       end
 
@@ -76,9 +81,9 @@ module OpenApi
         self[:requestBody] = RefObj.new(:requestBody, component_key).process
       end
 
-      def override_response code, type_hash
+      def merge_to_resp code, by:
         _response = self[:responses].fetch(code)
-        self[:responses][code] = _response.override(type_hash).process
+        self[:responses][code] = _response.override(by).process
       end
 
       def response_ref code_compkey_hash
@@ -105,33 +110,31 @@ module OpenApi
         body! media_type, desc, hash
       end
 
-      def security scheme_name, requirements = [ ]
-        self[:security] << { scheme_name => requirements }
+      def security_require scheme_name, scopes: [ ]
+        self[:security] << { scheme_name => scopes }
       end
 
+      alias security  security_require
+      alias auth      security_require
+      alias need_auth security_require
+
       def server url, desc
         self[:servers] << { url: url, description: desc }
       end
 
       def order *param_names
         self.param_order = param_names
+        self.param_use = param_order if param_use.blank?
+        self.param_skip = param_use - param_order
       end
 
       def param_examples exp_by = :all, examples_hash
         _process_objs
         exp_by = self[:parameters].map { |p| p[:name] } if exp_by == :all
-        # TODO: ref obj
-        # exp_in_params = self[:parameters].map { |p| p[:schema][:examples] }.compact
-        # examples_hash.map! do |key, value|
-        #   if value == []
-        #     if key.in?(exp_in_params.map { |e| e.keys }.flatten.uniq)
-        #       # TODO
-        #     end
-        #   end
-        # end
         self[:examples] = ExampleObj.new(examples_hash, exp_by).process
       end
-      alias_method :examples, :param_examples
+
+      alias examples param_examples
 
 
       def _process_objs
@@ -141,13 +144,13 @@ module OpenApi
 
         # Parameters sorting
         self[:parameters].clone.each do |p|
-          self[:parameters][param_order.index(p[:name])] = p
+          self[:parameters][param_order.index(p[:name]) || -1] = p
         end if param_order.present?
 
         self[:responses]&.each do |code, obj|
           self[:responses][code] = obj.process if obj.is_a?(ResponseObj)
         end
       end
-    end # ----------------------------------------- end of ApiInfoObj
+    end
   end
 end