zero-rails_openapi 1.7.0 → 2.0.0

data/README_zh.md

@@ -359,11 +359,11 @@
 
 
   # method signature
-  # `exp_by` (select_example_by): choose the example fields.
-  examples(exp_by = :all, examples_hash)
+  # `exp_params` (select_example_by): choose the example fields.
+  examples(exp_params = :all, examples_hash)
   # usage
   # it defines 2 examples by using parameter :id and :name
-  # if pass :all to `exp_by`, keys will be all the parameter's names.
+  # if pass :all to `exp_params`, keys will be all the parameter's names.
   examples [:id, :name], {
       :right_input => [ 1, 'user'], # == { id: 1, name: 'user' }
       :wrong_input => [ -1, ''   ]
@@ -425,7 +425,7 @@
       :password! => { type: String, pattern: /[0-9]{6,10}/, desc: 'password' },
       # optional
         :remarks => { type: String, desc: 'remarks' },
-  }, exp_by:            %i[ name password ],
+  }, exp_params:            %i[ name password ],
      examples: {         #    ↓        ↓
          :right_input => [ 'user1', '123456' ],
          :wrong_input => [ 'user2', 'abc'    ]
@@ -448,7 +448,7 @@
 
   1. `media_type`: we provide some [mapping](lib/oas_objs/media_type_obj.rb) from symbols to real media-types.
   2. `schema_info`: as above (see param).
-  3. `exp_by` and `examples`: for the above example, the following has the same effect:
+  3. `exp_params` and `examples`: for the above example, the following has the same effect:
      ```
      examples: {
          :right_input => { name: 'user1', password: '123456' },

data/{documentation/examples → examples}/open_api.rb

@@ -1,25 +1,23 @@
 require 'open_api'
 
-OpenApi::Config.tap do |c|
+OpenApi::Config.class_eval do
   # Config DSL
-  c.instance_eval do
-    open_api :zero_rails, base_doc_classes: [ApiDoc]
-    info version: '0.0.1', title: 'Zero Rails APIs', description: 'API documentation of Zero-Rails Application.'
-    server 'http://localhost:3000', desc: 'Main (production) server'
-    server 'http://localhost:3000', desc: 'Internal staging server for testing'
-    bearer_auth :Token
-    global_auth :Token
-  end
+  open_api :zero_rails, base_doc_classes: [ApiDoc]
+  info version: '0.0.1', title: 'Zero Rails APIs', description: 'API documentation of Zero-Rails Application.'
+  server 'http://localhost:3000', desc: 'Main (production) server'
+  server 'http://localhost:3000', desc: 'Internal staging server for testing'
+  bearer_auth :Token
+  global_auth :Token
 
   # [REQUIRED] The location where .json doc file will be output.
-  c.file_output_path = 'public/open_api'
+  self.file_output_path = 'public/open_api'
 
   # [Optional] Use this txt instead of running `rails routes`.
-  # c.rails_routes_file = 'config/routes.txt'
+  # self.rails_routes_file = 'config/routes.txt'
 
   # 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/
-  c.open_api_docs = {
+  self.open_api_docs = {
       blog_api: {
           # [REQUIRED] ZRO will scan all the descendants of the base_doc_classes, then generate their docs.
           base_doc_classes: [ApiController],
@@ -96,9 +94,7 @@ OpenApi::Config.tap do |c|
 
 end
 
-Object.const_set('Boolean', 'boolean') # Support `Boolean` writing in DSL
-
-OpenApi.write_docs generate_files: !Rails.env.production?
+OpenApi.write_docs if: !Rails.env.production?
 
 
 __END__

data/lib/oas_objs/callback_obj.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'oas_objs/helpers'
 
 module OpenApi
@@ -17,29 +19,22 @@ module OpenApi
 
       def process
         {
-            self.event_name => {
+            event_name => {
                 processed_url => {
-                    self.http_method.downcase.to_sym => processed_block
+                    http_method.downcase.to_sym => Api.new.run_dsl(&(self.block || -> { }))
                 }
             }
         }
       end
 
       def processed_url
-        self.callback_url.gsub(/{[^{}]*}/) do |exp|
+        callback_url.gsub(/{[^{}]*}/) do |exp|
           key_location, key_name = exp[1..-2].split
           connector = key_location == 'body' ? '#/' : '.'
           key_location = '$request.' + key_location
           ['{', key_location, connector, key_name, '}'].join
         end
       end
-
-      def processed_block
-        api = Api.new.merge! parameters: [ ], requestBody: '', responses: { }
-        api.instance_exec(&(self.block || -> { }))
-        api.process_objs
-        api.delete_if { |_, v| v.blank? }
-      end
     end
   end
 end

data/lib/oas_objs/combined_schema.rb

@@ -1,25 +1,29 @@
+# frozen_string_literal: true
+
 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
+      include Helpers
 
-      def initialize(combined_schema)
-        self.processed = { }
+      attr_accessor :processed, :mode, :schemas
 
+      def initialize(combined_schema)
         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
+        self.mode = combined_schema.keys.first.to_s.camelize(:lower).to_sym
+        self.schemas = combined_schema.values.first
       end
 
-      def process(options = { inside_desc: false })
-        processed[@mode] = @schemas.map do |schema|
-          type = schema.is_a?(Hash) ? schema[:type] : schema
-          schema = { } unless schema.is_a?(Hash)
-          SchemaObj.new(type, schema).process(options)
-        end
-        processed
+      def process
+        self.processed = {
+            mode =>
+                schemas.map do |schema|
+                  type = schema.is_a?(Hash) ? schema[:type] : schema
+                  schema = { } unless schema.is_a?(Hash)
+                  SchemaObj.new(type, schema).process
+                end
+        }
       end
     end
   end

data/lib/oas_objs/example_obj.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'oas_objs/helpers'
 require 'oas_objs/ref_obj'
 
@@ -7,7 +9,7 @@ module OpenApi
     class ExampleObj < Hash
       include Helpers
 
-      attr_accessor :processed, :examples_hash, :example_value, :keys_of_value
+      attr_accessor :examples_hash, :example_value, :keys_of_value
 
       def initialize(exp, keys_of_value = nil, multiple: false)
         multiple ? self.examples_hash = exp : self.example_value = exp
@@ -15,11 +17,11 @@ module OpenApi
       end
 
       def process
-        return self.processed = example_value if example_value
+        return example_value if example_value
+        return unless examples_hash
 
-        self.processed =
-          examples_hash.map do |(name, value)|
-            value =
+        examples_hash.map do |(name, value)|
+          value =
               if keys_of_value.present? && value.is_a?(Array)
                 { value: Hash[keys_of_value.zip(value)] }
               elsif value.is_a?(Symbol) && value['$']
@@ -28,8 +30,8 @@ module OpenApi
                 { value: value }
               end
 
-            { name => value }
-          end
+          { name => value }
+        end
       end
     end
   end

data/lib/oas_objs/helpers.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module OpenApi
   module Helpers
     def fusion
@@ -12,26 +14,8 @@ module OpenApi
       proc { |_, v| truly_present? v }
     end
 
-    # assign.to
-    def assign(value)
-      @assign = value.is_a?(Symbol) ? send("_#{value}") : value
-      self
-    end
-
-    # reducx.then_merge! => for Hash
-    def reducx(*values)
-      @assign = values.compact.reduce({ }, :merge!).keep_if &value_present
-      self
-    end
-
-    def to_processed(who)
-      return processed unless truly_present?(@assign)
-      processed[who.to_sym] = @assign
-      processed
-    end
-
-    def then_merge! # to_processed
-      processed.tap { |it| it.merge! @assign if truly_present?(@assign) }
+    def reducing(*values)
+      values.compact.reduce(processed, :merge!).keep_if &value_present
     end
   end
 end

data/lib/oas_objs/media_type_obj.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'oas_objs/schema_obj'
 require 'oas_objs/example_obj'
 
@@ -8,21 +10,20 @@ module OpenApi
       attr_accessor :media_type, :schema, :examples
 
       def initialize(media_type, hash)
-        examples_hash = hash.delete(:examples)
-        exp_by        = hash.delete(:exp_by)
-        schema_type   = hash.values_at(:type, :data).compact.first
-        exp_by        = schema_type.keys if exp_by == :all
-
-        self.examples   = ExampleObj.new(examples_hash, exp_by, multiple: true) if examples_hash.present?
-        self.media_type = media_type_mapping media_type
-        self.schema     = SchemaObj.new(schema_type, hash)
+        examples_hash   = hash.delete(:examples)
+        exp_params      = schema_type.keys if (exp_params = hash.delete(:exp_params)) == :all
+        self.examples   = ExampleObj.new(examples_hash, exp_params, multiple: true) if examples_hash.present?
+        self.media_type = media_type_mapping(media_type)
+        self.schema     = SchemaObj.new(hash.values_at(:type, :data).compact.first,
+                                        hash.except(:type, :data))
       end
 
       def process
+        return { } if media_type.nil?
         schema_processed = schema.process
         result = schema_processed.values.join.blank? ? { } : { schema: schema_processed }
         result[:examples] = examples.process unless examples.nil?
-        media_type.nil? ? { } : { media_type => result }
+        { media_type => result }
       end
 
       # https://swagger.io/docs/specification/media-types/
@@ -46,7 +47,6 @@ module OpenApi
         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 :pdf then   'application/pdf'
         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'

data/lib/oas_objs/param_obj.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'oas_objs/helpers'
 require 'oas_objs/schema_obj'
 
@@ -10,25 +12,20 @@ module OpenApi
 
       def initialize(name, param_type, type, required, schema)
         self.processed = {
-            name: name,
-            in: param_type,
+            name: name.to_s.delete('!').to_sym,
+            in: param_type.to_s.delete('!'),
             required: required.to_s[/req/].present?
         }
-        self.schema = schema.is_a?(CombinedSchema) ? schema : SchemaObj.new(type, schema)
-        merge! schema
+        merge!(self.schema = schema)
       end
 
       def process
-        assign(desc).to_processed :description
-        assign(schema.process).to_processed :schema
+        processed[:schema] = schema.process
+        desc = schema.processed[:description]
+        processed[:description] = desc if desc
         processed
       end
 
-      def desc
-        return self[:desc] || self[:description] if (self[:desc!] || self[:description!]).blank?
-        schema.__desc # not a copy of __desc, means desc() will change if schema.__desc changes.
-      end
-
       def name
         processed[:name]
       end

data/lib/oas_objs/ref_obj.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'oas_objs/helpers'
 
 module OpenApi

data/lib/oas_objs/request_body_obj.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'oas_objs/media_type_obj'
 require 'oas_objs/helpers'
 
@@ -9,18 +11,20 @@ module OpenApi
       include Helpers
 
       attr_accessor :processed, :media_types
+
       def initialize(required, desc)
         self.media_types = [ ]
         self.processed   = { required: required['req'].present?, description: desc }
       end
 
-      def add_or_fusion(media_type, hash)
+      def absorb(media_type, hash)
         media_types << MediaTypeObj.new(media_type, hash)
         self
       end
 
       def process
-        assign(media_types.map(&:process).reduce({ }, &fusion)).to_processed 'content'
+        content = media_types.map(&:process).reduce({ }, &fusion)
+        processed[:content] = content if content.present?
         processed
       end
     end

data/lib/oas_objs/response_obj.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'oas_objs/media_type_obj'
 require 'oas_objs/helpers'
 
@@ -13,14 +15,15 @@ module OpenApi
         self.processed   = { description: desc }
       end
 
-      def add_or_fusion(desc, media_type, hash)
+      def absorb(desc, media_type, hash)
         self.processed[:description] = desc if desc.present?
         media_types << MediaTypeObj.new(media_type, hash)
         self
       end
 
       def process
-        assign(media_types.map(&:process).reduce({ }, &fusion)).to_processed 'content'
+        content = media_types.map(&:process).reduce({ }, &fusion)
+        processed[:content] = content if content.present?
         processed
       end
     end

data/lib/oas_objs/schema_obj.rb

@@ -1,5 +1,6 @@
+# frozen_string_literal: true
+
 require 'oas_objs/helpers'
-require 'open_api/config'
 require 'oas_objs/ref_obj'
 require 'oas_objs/example_obj'
 require 'oas_objs/schema_obj_helpers'
@@ -11,28 +12,26 @@ module OpenApi
       include SchemaObjHelpers
       include Helpers
 
-      attr_accessor :processed, :type, :preprocessed
+      attr_accessor :processed, :type
 
-      def initialize(type, schema_info)
-        self.preprocessed = false
-        self.processed = { }
-        self.type = type
-        merge! schema_info
+      def initialize(type = nil, schema)
+        self.merge!(schema)
+        self.processed = { type: nil, format: nil, **schema.except(:type, :range, :enum!, *SELF_MAPPING.values.flatten) }
+        self.type = type || self[:type]
       end
 
-      def process(options = { inside_desc: false })
-        processed.merge!(processed_type)
-        reducx(additional_properties, enum_and_length, range, format, pattern_default_and_other, desc(options)).then_merge!
+      def process
+        processed.merge!(recg_schema_type)
+        reducing(additional_properties, enum, length, range, format, other, desc)
       end
 
-      def desc(inside_desc:)
-        result = __desc ? auto_generate_desc : _desc
-        return unless inside_desc
+      def desc
+        return unless (result = @bang_enum.present? ? auto_generate_desc : _desc)
         { description: result }
       end
 
-      def processed_type(type = self.type)
-        t = type.class.in?([Hash, Array, Symbol]) ? type : type.to_s.downcase
+      def recg_schema_type(t = self.type)
+        t = t.class.in?([Hash, Array, Symbol]) ? t : t.to_s.downcase
         if t.is_a? Hash
           hash_type(t)
         elsif t.is_a? Array
@@ -56,93 +55,75 @@ module OpenApi
       end
 
       def additional_properties
-        return { } if processed[:type] != 'object' || _addProp.nil?
+        return if processed[:type] != 'object' || _addProp.nil?
         {
-            additionalProperties: SchemaObj.new(_addProp, { }).process(inside_desc: true)
+            additionalProperties: SchemaObj.new(_addProp, { }).process
         }
       end
 
-      def enum_and_length
-        process_enum_info
-        process_range_enum_and_lth
-
-        # generate length range fields by _lth array
-        if (lth = _length || '').is_a?(Array)
-          min, max = [lth.first&.to_i, lth.last&.to_i]
-        elsif lth['ge']
-          min = lth.to_s.split('_').last.to_i
-        elsif lth['le']
-          max = lth.to_s.split('_').last.to_i
+      def enum
+        self._enum = str_range_to_a(_enum) if _enum.is_a?(Range)
+        # Support this writing for auto generating desc from enum.
+        #   enum!: {
+        #     'all_desc': :all,
+        #     'one_desc': :one
+        # }
+        if (@bang_enum = self[:enum!])
+          self._enum ||= @bang_enum.is_a?(Hash) ? @bang_enum.values : @bang_enum
         end
+        { enum: _enum }
+      end
 
-        if processed[:type] == 'array'
-          { minItems: min, maxItems: max }
+      def length
+        return unless _length
+        self._length = str_range_to_a(_length) if _length.is_a?(Range)
+
+        if _length.is_a?(Array)
+          min, max = [ _length.first&.to_i, _length.last&.to_i ]
         else
-          { minLength: min, maxLength: max }
-        end.merge!(enum: _enum).keep_if &value_present
+          min, max = _length[/ge_(.*)/, 1]&.to_i, _length[/le_(.*)/, 1]&.to_i
+        end
+
+        processed[:type] == 'array' ? { minItems: min, maxItems: max } : { minLength: min, maxLength: max }
       end
 
       def range
-        range = _range || { }
+        (range = self[:range]) or return
         {
                      minimum: range[:gt] || range[:ge],
-            exclusiveMinimum: range[:gt].present? ? true : nil,
+            exclusiveMinimum: range[:gt].present? || nil,
                      maximum: range[:lt] || range[:le],
-            exclusiveMaximum: range[:lt].present? ? true : nil
-        }.keep_if &value_present
+            exclusiveMaximum: range[:lt].present? || nil
+        }
       end
 
       def format
-        result = { is: _is }
-        # `format` that generated in process_type() may be overwrote here.
-        result[:format] = _format || _is if processed[:format].blank? || _format.present?
-        result
+        { format: self[:format] || self[:is_a] } unless processed[:format]
       end
 
-      def pattern_default_and_other
+      def other
         {
             pattern:  _pattern.is_a?(String) ? _pattern : _pattern&.inspect&.delete('/'),
-            default:  _default,
-            example:  _exp.present? ? ExampleObj.new(_exp).process : nil,
-            examples: _exps.present? ? ExampleObj.new(_exps, self[:exp_by], multiple: true).process : nil,
-            as: _as, permit: _permit, not_permit: _npermit, req_if: _req_if, opt_if: _opt_if, blankable: _blank
+            example:  ExampleObj.new(self[:example]).process,
+            examples: ExampleObj.new(self[:examples], self[:exp_params], multiple: true).process
         }
       end
 
 
-      { # SELF_MAPPING
+      SELF_MAPPING = {
           _enum:    %i[ enum in  values  allowable_values ],
-          _value:   %i[ must_be  value   allowable_value  ],
-          _range:   %i[ range    number_range             ],
           _length:  %i[ length   lth     size             ],
-          _format:  %i[ format   fmt                      ],
-          _pattern: %i[ pattern  regexp  pt   reg         ],
-          _default: %i[ default  dft     default_value    ],
+          _pattern: %i[ pattern  regexp                   ],
           _desc:    %i[ desc     description  d           ],
-          __desc:   %i[ desc!    description! d!          ],
-          _exp:     %i[ example                           ],
-          _exps:    %i[ examples                          ],
           _addProp: %i[ additional_properties add_prop values_type ],
-          _is:      %i[ is_a     is                       ], # NOT OAS Spec, see documentation/parameter.md
-          _as:      %i[ as   to  for     map  mapping     ], # NOT OAS Spec, it's for zero-params_processor
-          _permit:  %i[ permit   pmt                      ], # ditto
-          _npermit: %i[ npmt     not_permit   unpermit    ], # ditto
-          _req_if:  %i[ req_if   req_when                 ], # ditto
-          _opt_if:  %i[ opt_if   opt_when                 ], # ditto
-          _blank:   %i[ blank    blankable                ], # ditto
       }.each do |key, aliases|
-        define_method key do
-          return self[key] unless self[key].nil?
-          aliases.each { |alias_name| self[key] = self[alias_name] if self[key].nil? }
-          self[key]
-        end
+        define_method(key)       { self[key] ||= self.values_at(*aliases).compact.first }
         define_method("#{key}=") { |value| self[key] = value }
       end
     end
   end
 end
 
-
 __END__
 
 Schema Object Examples