zero-rails_openapi 1.4.0 → 1.4.1

data/documentation/examples/auto_gen_doc.rb

@@ -10,7 +10,7 @@ module AutoGenDoc
     def inherited(subclass)
       super
       subclass.class_eval do
-        break unless self.name.match? /sController|sDoc/
+        break unless self.name.match?(/sController|sDoc/)
         ctrl_path self.name.sub('Doc', '').downcase.gsub('::', '/') if self.name.match?(/sDoc/)
         open_api_dry
       end

data/documentation/examples/examples_controller.rb

@@ -3,6 +3,7 @@ class Api::V1::ExamplesController < Api::V1::BaseController
 
   components do
     schema :DogSchema => [ String, dft: 'doge' ]
+    schema :PetSchema => [ not: [ Integer, Boolean ] ]
     query! :UidQuery  => [ :uid, String, desc: 'user uid' ]
     path!  :IdPath    => [ :id, Integer, desc: 'product id' ]
     resp   :BadRqResp => [ 'bad request', :json ]
@@ -27,7 +28,20 @@ class Api::V1::ExamplesController < Api::V1::BaseController
     query  :email, String,  lth: :ge_3,     default: email  # is_a: :email
     file   :pdf, 'upload a file: the media type should be application/pdf'
 
+    query :test_type, type: String
+    query :combination, one_of: [ :DogSchema, String, { type: Integer, desc: 'integer input'}]
+    form '', data: {
+        :combination => { any_of: [ Integer, String ] }
+    }
+
     response :success, 'success response', :json, type: :DogSchema
+    merge_to_resp 200, by: {
+        data: {
+            type: [
+                String
+            ]
+        }
+    }
 
     security :ApiKeyAuth
   end

data/documentation/examples/goods_doc.rb

@@ -1,9 +1,8 @@
 class V2::GoodsDoc < BaseDoc
   SCHEMA_DRY = { a: 1, b: 2 }
 
-  api :index, 'GET list of goods.', builder: :index, # jbuilder templates is set in initializers/open_api.rb
-           use: [ 'Token', :page, :rows ] do # use parameters write in AutoGenDoc#api_dry
-           # skip: [ 'Token' ] do # you can also skip parameters
+  #                                 skip: [ 'Token' ] do # you can also skip parameters
+  api :index, 'GET list of goods.', use: [ 'Token', :page, :rows ] do # use parameters write in AutoGenDoc#api_dry
     desc 'listing goods',
          view!: 'search view, allows:<br/>',
          search_type!: 'search field, allows:<br/>'
@@ -28,7 +27,7 @@ class V2::GoodsDoc < BaseDoc
   end
 
 
-  api :create, 'POST create a good', builder: :success_or_not, use: 'Token' do
+  api :create, 'POST create a good', use: 'Token' do
     form! 'for creating a good', data: {
                :name! => { type: String,  desc: 'good\'s name' },
         :category_id! => { type: Integer, desc: 'sub_category\'s id', npmt: true, range: { ge: 1 }, as: :cate  },
@@ -46,8 +45,8 @@ class V2::GoodsDoc < BaseDoc
   end
 
 
-  api :show, 'GET the specified Good.', builder: :show, use: [ 'Token', :id ]
+  api :show, 'GET the specified Good.', use: [ 'Token', :id ]
 
 
-  api :destroy, 'DELETE the specified Good.', builder: :success_or_not, use: [ 'Token', :id ]
+  api :destroy, 'DELETE the specified Good.', use: [ 'Token', :id ]
 end

data/documentation/examples/open_api.rb

@@ -80,7 +80,7 @@ OpenApi::Config.tap do |c|
           #   The securitySchemes and security keywords are used to describe the authentication methods used in your API.
           #   https://swagger.io/docs/specification/authentication/
           # Security Scheme Object: An object to hold reusable Security Scheme Objects.
-          security_schemes: {
+          securitySchemes: {
               ApiKeyAuth: { type: 'apiKey', name: 'server_token', in: 'query' },
               Token: { type: 'http', scheme: 'bearer', bearerFormat: 'JWT' }
           },
@@ -94,57 +94,6 @@ OpenApi::Config.tap do |c|
       }
   }
 
-  c.generate_jbuilder_file  = true
-  c.overwrite_jbuilder_file = false
-  c.jbuilder_templates = {
-      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
 
 Object.const_set('Boolean', 'boolean') # Support `Boolean` writing in DSL

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?
     end

data/lib/oas_objs/param_obj.rb

@@ -24,11 +24,8 @@ module OpenApi
       end
 
       def desc
-        if __desc.present?
-          schema.preprocess_with_desc __desc, self[:name]
-        else
-          _desc
-        end
+        return _desc unless __desc.present?
+        schema.preprocess_with_desc __desc, self[:name]
       end
 
 

data/lib/oas_objs/schema_obj.rb

@@ -2,11 +2,13 @@ require 'oas_objs/helpers'
 require 'open_api/config'
 require 'oas_objs/ref_obj'
 require 'oas_objs/example_obj'
+require 'oas_objs/schema_obj_helpers'
 
 module OpenApi
   module DSL
     # https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md#schemaObject
     class SchemaObj < Hash
+      include SchemaObjHelpers
       include Helpers
 
       attr_accessor :processed, :type
@@ -28,19 +30,20 @@ module OpenApi
         return processed if @preprocessed
 
         processed.merge! processed_type
-        reducx processed_enum_and_length,
-               processed_range,
-               processed_is_and_format(param_name),
-               {
-                   pattern:    _pattern&.inspect&.delete('/'),
-                   default:    _default.nil? ? nil : '_default',
-                   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!
+        reducx(
+            processed_enum_and_length,
+            processed_range,
+            processed_is_and_format(param_name),
+            {
+                pattern:    _pattern&.inspect&.delete('/'),
+                default:    _default.nil? ? nil : '_default',
+                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!
         processed[:default] = _default unless _default.nil?
 
-        reducx(processed_desc options).then_merge!
+        reducx(processed_desc(options)).then_merge!
       end
 
       alias process process_for
@@ -53,44 +56,16 @@ module OpenApi
       end
 
       def processed_desc(options)
-        result = __desc ? self.__desc = process_desc : _desc
+        result = __desc ? self.__desc = auto_generate_desc : _desc
         options[:desc_inside] ? { description: result } : nil
       end
 
-      # TODO: more info
-      # TODO: desc configure
-      def process_desc
-        if processed[:enum].present?
-          if @enum_info.present?
-            @enum_info.each_with_index do |(info, value), index|
-              __desc.concat "<br/>#{index + 1}/ #{info}: #{value}"
-            end
-          else
-            processed[:enum].each_with_index do |value, index|
-              __desc.concat "<br/>#{index + 1}/ #{value}"
-            end
-          end
-        end
-        __desc
-      end
-
       def processed_type(type = self.type)
         t = type.class.in?([Hash, Array, Symbol]) ? type : type.to_s.downcase
         if t.is_a? Hash
-          # 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)
-          # 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
+          processed_hash_type(t)
         elsif t.is_a? Array
-          recursive_array_type t
+          recursive_array_type(t)
         elsif t.is_a? Symbol
           RefObj.new(:schema, t).process
         elsif t.in? %w[float double int32 int64] # to README: 这些值应该传 string 进来, symbol 只允许 $ref
@@ -106,53 +81,24 @@ module OpenApi
         end
       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.keys & %i[ type one_of any_of all_of not ]).present?
-
-        _schema = {
-            type: 'object',
-            properties: { },
-            required: [ ]
-        }
-        t.each do |prop_name, prop_type|
-          @prop_name = prop_name
-          _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)
-      end
-
-      def recursive_array_type(t)
-        if t.is_a? Array
-          {
-              type: 'array',
-              # TODO: [[String], [Integer]] <= One Of? Object?(0=>[S], 1=>[I])
-              items: recursive_array_type(t.first)
-          }
+      def processed_hash_type(t)
+        # 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)
+          # 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
-          processed_type t
+          recursive_obj_type(t)
         end
       end
 
       def processed_enum_and_length
-        # Support this writing for auto generating desc from enum.
-        #   enum: {
-        #     'all_data': :all,
-        #     'one_page': :one
-        # }
-        if _enum.is_a? Hash
-          @enum_info = _enum
-          self._enum = _enum.values
-        end
-
-        %i[_enum _length].each do |key|
-          value = self.send(key)
-          self[key] = value.to_a if value.present? && value.is_a?(Range)
-        end
-
-        # generate_enums_by_enum_array
-        values = _enum || _value
-        self._enum = Array(values) if truly_present?(values)
+        process_enum_info
+        process_enum_lth_range
 
         # generate length range fields by _lth array
         lth = _length || [ ]
@@ -180,16 +126,17 @@ module OpenApi
         recognize_is_options_in name
         { }.tap do |it|
           # `format` that generated in process_type() may be overwrote here.
-          it.merge!(format: _format || _is) if processed[:format].blank? || _format.present?
-          it.merge! is: _is
+          it[:format] = _format || _is if processed[:format].blank? || _format.present?
+          it[:is] = _is
         end
       end
 
       def recognize_is_options_in(name)
+        return unless _is.nil?
         # 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}/)
-        end if _is.nil?
+          (self._is = pattern) or break if name.match?(/#{pattern}/)
+        end
       end
 
 
@@ -211,10 +158,12 @@ module OpenApi
           _opt_if:  %i[ opt_if   opt_when                 ], # NOT OAS Spec, it's for zero-params_processor
       }.each do |key, aliases|
         define_method key do
+          return self[key] unless self[key].nil?
+          
           aliases.each do |alias_name|
             break if self[key] == false
             self[key] ||= self[alias_name]
-          end if self[key].nil?
+          end
           self[key]
         end
         define_method "#{key}=" do |value| self[key] = value end

data/lib/oas_objs/schema_obj_helpers.rb

@@ -0,0 +1,68 @@
+module OpenApi
+  module DSL
+    module SchemaObjHelpers
+      # TODO: more info and desc configure
+      def auto_generate_desc
+        if processed[:enum].present?
+          if @enum_info.present?
+            @enum_info.each_with_index do |(info, value), index|
+              __desc.concat "<br/>#{index + 1}/ #{info}: #{value}"
+            end
+          else
+            processed[:enum].each_with_index do |value, index|
+              __desc.concat "<br/>#{index + 1}/ #{value}"
+            end
+          end
+        end
+        __desc
+      end
+
+      def recursive_obj_type(t) # ZRO use { prop_name: prop_type } to represent object structure
+        return processed_type(t) if !t.is_a?(Hash) || (t.keys & %i[ type one_of any_of all_of not ]).present?
+
+        _schema = {
+            type: 'object',
+            properties: { },
+            required: [ ]
+        }
+        t.each do |prop_name, prop_type|
+          @prop_name = prop_name
+          _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)
+      end
+
+      def recursive_array_type(t)
+        return processed_type(t) unless t.is_a? Array
+
+        {
+            type: 'array',
+            # TODO: [[String], [Integer]] <= One Of? Object?(0=>[S], 1=>[I])
+            items: recursive_array_type(t.first)
+        }
+      end
+
+      def process_enum_lth_range
+        self[:_enum] = _enum.to_a if _enum.present? && _enum.is_a?(Range)
+        self[:_length] = _length.to_a if _length.present? && _length.is_a?(Range)
+
+        # generate_enums_by_enum_array
+        values = _enum || _value
+        self._enum = Array(values) if truly_present?(values)
+      end
+
+      def process_enum_info
+        # Support this writing for auto generating desc from enum.
+        #   enum: {
+        #     'all_data': :all,
+        #     'one_page': :one
+        # }
+        if _enum.is_a? Hash
+          @enum_info = _enum
+          self._enum = _enum.values
+        end
+      end
+    end
+  end
+end

data/lib/open_api/config.rb

@@ -14,10 +14,18 @@ module OpenApi
       true
     end
 
+    cattr_accessor :doc_location do
+      ['./app/**/*_doc.rb']
+    end
+
     cattr_accessor :rails_routes_file do
       nil
     end
 
+    cattr_accessor :active_record_base do
+      ApplicationRecord
+    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 :open_api_docs do

data/lib/open_api/config_dsl.rb

@@ -9,8 +9,8 @@ module OpenApi
           open_api_docs[name] = { root_controller: root_controller }
         end
 
-        def info version:, title:, **addition
-          open_api_docs[@api][:info] = { version: version, title: title, **addition }
+        def info version:, title:, desc: '', **addition
+          open_api_docs[@api][:info] = { version: version, title: title, description:  desc, **addition }
         end
 
         def server url, desc: ''
@@ -19,7 +19,7 @@ module OpenApi
 
         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
+          (open_api_docs[@api][:securitySchemes] ||= { })[scheme_name] = other_info
         end
 
         def base_auth scheme_name, other_info = { }
@@ -42,7 +42,7 @@ module OpenApi
         class << self
           alias global_security global_security_require
           alias global_auth     global_security_require
-          alias auth_scheme security_scheme
+          alias auth_scheme     security_scheme
         end
       end
     end