zero-rails_openapi 1.0.0

data/lib/oas_objs/schema_obj.rb

@@ -0,0 +1,187 @@
+require 'oas_objs/helpers'
+require 'open_api/config'
+require 'oas_objs/ref_obj'
+
+module OpenApi
+  module DSL
+    # https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md#schemaObject
+    class SchemaObj < Hash
+      include Helpers
+
+      attr_accessor :processed, :type
+      def initialize(type, schema_hash)
+        self.processed = { }
+        # [Note] Here is no limit to type, even if the input isn't up to OAS,
+        #          like: double, float, hash.
+        #        My consideration is, OAS can't express some cases like:
+        #          `total_price` should be double, is_a `price`, and match /^.*\..*$/
+        #        However, user can decide how to write --
+        #          `type: number, format: double`, or `type: double`
+        self.type = type
+        self.merge! schema_hash
+      end
+
+
+      def process_for(param_name = nil)
+        processed.merge! processed_type
+        all(processed_enum_and_length,
+            processed_range,
+            processed_is_and_format(param_name),
+            { pattern: _pattern&.inspect&.delete('/'),
+              default: _default }
+        ).for_merge
+      end
+      alias_method :process, :process_for
+
+      def processed_type(type = self.type)
+        t = type.class.in?([Hash, Array, Symbol]) ? type : "#{type}".downcase
+        if t.is_a? Hash
+          recursive_obj_type t
+        elsif t.is_a? Array
+          recursive_array_type t
+        elsif t.is_a? Symbol
+          RefObj.new(:schema, t).process
+        elsif t.in? %w[float double int32 int64] #  TTTTTIP: 这些值应该传 string 进来, symbol 只允许 $ref
+          { type: t.match?('int') ? 'integer' : 'number', format: t}
+        elsif t.in? %w[binary base64]
+          { type: 'string', format: t}
+        elsif t.eql? 'file'
+          { type: 'string', format: OpenApi.config.dft_file_format }
+        else # other string
+          { type: t }
+        end
+      end
+      def recursive_obj_type(t) # DSL use { k:v } to represent object structure
+        return processed_type(t) unless t.is_a? Hash
+
+        _schema = {
+            type: 'object',
+            properties: { },
+            required: [ ]
+        }
+        t.each do |k, v|
+          _schema[:required] << "#{k}".delete('!') if "#{k}".match? '!'
+          _schema[:properties]["#{k}".delete('!').to_sym] = recursive_obj_type v
+        end
+        _schema.keep_if &value_present
+      end
+      def recursive_array_type(t)
+        if t.is_a? Array
+          {
+              type: 'array',
+              items: recursive_array_type(t[0])
+          }
+        else
+          processed_type t
+        end
+      end
+
+      def processed_enum_and_length
+        %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 = (values.is_a?(Array) ? values : [values]) if truly_present?(values)
+
+        # generate length range fields by _lth array
+        lth = _length || [ ]
+        if self[:type] == 'array'
+          {
+              minItems: lth.is_a?(Array) ? lth.first : nil,
+              maxItems: lth.is_a?(Array) ? lth.last : nil
+          }
+        else
+          {
+              minLength: lth.is_a?(Array) ? lth.first : ("#{lth}".match?('ge') ? "#{lth}".split('_').last.to_i : nil),
+              maxLength: lth.is_a?(Array) ? lth.last : ("#{lth}".match?('le') ? "#{lth}".split('_').last.to_i : nil)
+          }
+        end.merge!(enum: _enum).keep_if &value_present
+      end
+
+      def processed_range
+        range = _range || { }
+        {
+            minimum: range[:gt] || range[:ge],
+            exclusiveMinimum: range[:gt].present? ? true : nil,
+            maximum: range[:lt] || range[:le],
+            exclusiveMaximum: range[:lt].present? ? true : nil
+        }.keep_if &value_present
+      end
+
+      def processed_is_and_format(name)
+        return if name.nil?
+        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
+        end
+      end
+      def recognize_is_options_in(name)
+        # identify whether `is` patterns matched the name, if so, generate `is`.
+        OpenApi.config.is_options.each do |pattern|
+          self._is = pattern or break if "#{name}".match? /#{pattern}/
+        end if _is.nil?
+        self.delete :_is if _is.in?([:x, :we])
+      end
+
+
+      { # SELF_MAPPING
+        _enum:    %i[enum     values  allowable_values],
+        _value:   %i[must_be  value   allowable_value ],
+        _range:   %i[range    number_range            ],
+        _length:  %i[length   lth                     ],
+        _is:      %i[is_a     is                      ], # NOT OAS Spec, just a addition
+        _format:  %i[format   fmt                     ],
+        _pattern: %i[pattern  regexp  pr   reg        ],
+        _default: %i[default  dft     default_value   ],
+      }.each do |key, aliases|
+        define_method key do
+          aliases.each do |alias_name|
+            break if self[key] == false
+            self[key] ||= self[alias_name]
+          end if self[key].nil?
+          self[key]
+        end
+        define_method "#{key}=" do |value| self[key] = value end
+      end
+    end
+  end
+end
+
+
+__END__
+
+Schema Object Examples
+
+Primitive Sample
+
+{
+  "type": "string",
+  "format": "email"
+}
+
+Simple Model
+
+{
+  "type": "object",
+  "required": [
+    "name"
+  ],
+  "properties": {
+    "name": {
+      "type": "string"
+    },
+    "address": {
+      "$ref": "#/components/schemas/Address"
+    },
+    "age": {
+      "type": "integer",
+      "format": "int32",
+      "minimum": 0
+    }
+  }
+}

data/lib/open_api.rb

@@ -0,0 +1,9 @@
+require "open_api/version"
+require "open_api/config"
+require "open_api/generator"
+require "open_api/dsl"
+
+module OpenApi
+  include Config
+  include Generator
+end

data/lib/open_api/config.rb

@@ -0,0 +1,34 @@
+module OpenApi
+  module Config
+    def self.included(base)
+      base.extend ClassMethods
+    end
+
+    DEFAULT_CONFIG = {
+        is_options: %w[email phone password uuid uri url time date],
+        dft_file_format: 'binary'
+    }
+
+    module ClassMethods
+      def config
+        @config ||= ActiveSupport::InheritableOptions.new(DEFAULT_CONFIG)
+      end
+
+      def configure(&block)
+        config.instance_eval &block
+      end
+
+      ### config options
+      # register_apis = {
+      #     version: {
+      #         :file_output_path, :root_controller
+      #         info: {}
+      #     }}
+      # is_options = %w[]
+
+      def apis
+        @apis ||= @config.register_apis
+      end
+    end
+  end
+end

data/lib/open_api/dsl.rb

@@ -0,0 +1,58 @@
+require 'open_api/dsl_inside_block'
+
+module OpenApi
+  module DSL
+    def self.included(base)
+      base.extend ClassMethods
+    end
+
+    # TODO: Doc-Block Comments
+    module ClassMethods
+      def apis_set desc = '', external_doc_url = '', &block
+        @_api_infos, @_ctrl_infos = { }, { }
+        # current `tag`, this means that tags is currently divided by controllers.
+        tag = @_ctrl_infos[:tag] = { name: controller_name.camelize }
+        tag[:description]  = desc if desc.present?
+        tag[:externalDocs] = { description: 'ref', url: external_doc_url } if external_doc_url.present?
+
+        current_ctrl = @_ctrl_infos[:components] = CtrlInfoObj.new
+        current_ctrl.instance_eval &block if block_given?
+      end
+
+      def open_api method, summary = '', &block
+        # select the routing info corresponding to the current method from the routing list.
+        action_path = "#{controller_path}##{method}"
+        routes_info = ctrl_routes_list.select { |api| api[:action_path].match? /^#{action_path}$/ }.first
+        puts "[zero-rails_openapi] Routing mapping failed: #{controller_path}##{method}" or return if routes_info.nil?
+
+        # structural { path: { http_method:{ } } }, for Paths Object.
+        # it will be merged into :paths
+        path = @_api_infos[routes_info[:path]] ||= { }
+        current_api = path[routes_info[:http_verb]] =
+            ApiInfoObj.new(action_path).merge!( summary: summary, operationId: method, tags: [controller_name.camelize] )
+
+        current_api.tap do |it|
+          it.instance_eval &block if block_given?
+          [method, :all].each do |key| # blocks_store_key
+            @apis_blocks[key]&.each { |blk| it.instance_eval &blk }
+          end
+        end
+      end
+
+      # For DRY; method could be symbol array
+      def open_api_set method = :all, desc = '', &block
+        @apis_blocks ||= { }
+        if method.is_a? Array
+          method.each { |m| (@apis_blocks[m.to_sym] ||= [ ]) << block }
+        else
+          (@apis_blocks[method.to_sym] ||= [ ]) << block
+        end
+      end
+
+      def ctrl_routes_list
+        @routes_list ||= Generator.generate_routes_list
+        @routes_list[controller_path]
+      end
+    end
+  end
+end

data/lib/open_api/dsl_inside_block.rb

@@ -0,0 +1,175 @@
+require 'oas_objs/schema_obj'
+require 'oas_objs/param_obj'
+require 'oas_objs/response_obj'
+require 'oas_objs/request_body_obj'
+require 'oas_objs/ref_obj'
+
+module OpenApi
+  module DSL
+    module CommonDSL
+      def arrow_writing_support
+        Proc.new do |args, executor|
+          if args.count == 1 && args[0].is_a?(Hash)
+            send(executor, args[0].keys.first, *args[0].values.first)
+          else
+            send(executor, *args)
+          end
+        end
+      end
+
+      %i[header header! path path! query query! cookie cookie!].each do |param_type|
+        define_method param_type do |*args|
+          @param_type = param_type
+          _param_agent *args
+        end
+      end
+
+      %i[body body!].each do |method|
+        define_method method do |*args|
+          @_method_name = method
+          _request_body_agent *args
+        end
+      end
+
+      # code represents `component_key` when u declare response component
+      def _response code, desc, media_type = nil, schema_hash = { }
+        (self[:responses] ||= { }).merge! ResponseObj.new(code, desc, media_type, schema_hash).process
+      end
+
+      def response *args
+        arrow_writing_support.call(args, :_response)
+      end
+
+      def default_response desc, media_type = nil, schema_hash = { }
+        response :default, desc, media_type, schema_hash
+      end
+
+      { # alias_methods mapping
+        response:         %i[resp            error_response                 ],
+        default_response: %i[dft_resp                                       ],
+        error_response:   %i[other_response  oth_resp        error  err_resp],
+      }.each do |original_name, aliases|
+        aliases.each do |alias_name|
+          alias_method alias_name, original_name
+        end
+      end
+    end # ----------------------------------------- end of CommonDSL
+
+
+
+
+    class CtrlInfoObj < Hash
+      include DSL::CommonDSL
+
+      def _schema component_key, type, schema_hash
+        (self[:schemas] ||= { }).merge! component_key => SchemaObj.new(type, schema_hash).process
+      end
+      def schema *args
+        arrow_writing_support.call(args, :_schema)
+      end
+
+      def param component_key, param_type, name, type, required, schema_hash = { }
+        (self[:parameters] ||= { })
+            .merge! component_key => ParamObj.new(name, param_type, type, required, schema_hash).process
+      end
+
+      def _param_agent *args
+        arrow_writing_support.call(args, :_param_arg_agent)
+      end
+
+      def _param_arg_agent component_key, name, type, schema_hash = { }
+        param component_key, "#{@param_type}".delete('!'), name, type,
+              ("#{@param_type}".match?(/!/) ? :req : :opt), schema_hash
+      end
+
+      def request_body component_key, required, media_type, desc = '', schema_hash = { }
+        self[:requestBodies] = { component_key => RequestBodyObj.new(required, media_type, desc, schema_hash).process }
+      end
+
+      def _request_body_agent *args
+        arrow_writing_support.call(args, :_request_body_arg_agent)
+      end
+
+      def _request_body_arg_agent component_key, media_type, desc = '', schema_hash = { }
+        request_body component_key, ("#{@_method_name}".match?(/!/) ? :req : :opt), media_type, desc, schema_hash
+      end
+    end # ----------------------------------------- end of CtrlInfoObj
+
+
+
+
+    class ApiInfoObj < Hash
+      include DSL::CommonDSL
+
+      attr_accessor :action_path
+      def initialize(action_path)
+        self.action_path = action_path
+      end
+
+      def this_api_is_invalid! explain = ''
+        self[:deprecated] = true
+      end
+      alias_method :this_api_is_expired!,     :this_api_is_invalid!
+      alias_method :this_api_is_unused!,      :this_api_is_invalid!
+      alias_method :this_api_is_under_repair, :this_api_is_invalid!
+
+      def desc desc, inputs_descs = { }
+        @inputs_descs = inputs_descs
+        self[:description] = desc
+      end
+
+      def param param_type, name, type, required, schema_hash = { }
+        schema_hash[:desc] = @inputs_descs[name] if @inputs_descs&.[](name).present?
+        (self[:parameters] ||= [ ]) << ParamObj.new(name, param_type, type, required, schema_hash).process
+      end
+
+      def _param_agent name, type, schema_hash = { }
+        param "#{@param_type}".delete('!'), name, type, ("#{@param_type}".match?(/!/) ? :req : :opt), schema_hash
+      end
+
+      def param_ref component_key, *keys
+        (self[:parameters] ||= [ ]).concat [component_key].concat(keys).map { |key| RefObj.new(:parameter, key).process }
+      end
+
+      def request_body required, media_type, desc = '', schema_hash = { }
+        self[:requestBody] = RequestBodyObj.new(required, media_type, desc, schema_hash).process
+      end
+
+      def _request_body_agent media_type, desc = '', schema_hash = { }
+        request_body ("#{@_method_name}".match?(/!/) ? :req : :opt), media_type, desc, schema_hash
+      end
+
+      def body_ref component_key
+        self[:requestBody] = RefObj.new(:parameter, component_key).process
+      end
+
+      def response_ref code_compkey_hash
+        code_compkey_hash.each do |code, component_key|
+          (self[:responses] ||= { }).merge! code => RefObj.new(:response, component_key).process
+        end
+      end
+
+      # 注意同时只能写一句 request body，包括 form 和 file
+      def form desc = '', schema_hash = { }
+        body :form, desc, schema_hash
+      end
+      def form! desc = '', schema_hash = { }
+        body! :form, desc, schema_hash
+      end
+      def file media_type, desc = '', schema_hash = { type: File }
+        body media_type, desc, schema_hash
+      end
+      def file! media_type, desc = '', schema_hash = { type: File }
+        body! media_type, desc, schema_hash
+      end
+
+      def security scheme_name, requirements = [ ]
+        (self[:security] ||= [ ]) << { scheme_name => requirements }
+      end
+
+      def server url, desc
+        (self[:servers] ||= [ ]) << { url: url, description: desc }
+      end
+    end # ----------------------------------------- end of ApiInfoObj
+  end
+end