meta-api 0.0.2 → 0.0.3

data/examples/rails_app/spec/spec_helper.rb

@@ -0,0 +1,94 @@
+# This file was generated by the `rails generate rspec:install` command. Conventionally, all
+# specs live under a `spec` directory, which RSpec adds to the `$LOAD_PATH`.
+# The generated `.rspec` file contains `--require spec_helper` which will cause
+# this file to always be loaded, without a need to explicitly require it in any
+# files.
+#
+# Given that it is always loaded, you are encouraged to keep this file as
+# light-weight as possible. Requiring heavyweight dependencies from this file
+# will add to the boot time of your test suite on EVERY test run, even for an
+# individual file that may not need all of that loaded. Instead, consider making
+# a separate helper file that requires the additional dependencies and performs
+# the additional setup, and require it from the spec files that actually need
+# it.
+#
+# See https://rubydoc.info/gems/rspec-core/RSpec/Core/Configuration
+RSpec.configure do |config|
+  # rspec-expectations config goes here. You can use an alternate
+  # assertion/expectation library such as wrong or the stdlib/minitest
+  # assertions if you prefer.
+  config.expect_with :rspec do |expectations|
+    # This option will default to `true` in RSpec 4. It makes the `description`
+    # and `failure_message` of custom matchers include text for helper methods
+    # defined using `chain`, e.g.:
+    #     be_bigger_than(2).and_smaller_than(4).description
+    #     # => "be bigger than 2 and smaller than 4"
+    # ...rather than:
+    #     # => "be bigger than 2"
+    expectations.include_chain_clauses_in_custom_matcher_descriptions = true
+  end
+
+  # rspec-mocks config goes here. You can use an alternate test double
+  # library (such as bogus or mocha) by changing the `mock_with` option here.
+  config.mock_with :rspec do |mocks|
+    # Prevents you from mocking or stubbing a method that does not exist on
+    # a real object. This is generally recommended, and will default to
+    # `true` in RSpec 4.
+    mocks.verify_partial_doubles = true
+  end
+
+  # This option will default to `:apply_to_host_groups` in RSpec 4 (and will
+  # have no way to turn it off -- the option exists only for backwards
+  # compatibility in RSpec 3). It causes shared context metadata to be
+  # inherited by the metadata hash of host groups and examples, rather than
+  # triggering implicit auto-inclusion in groups with matching metadata.
+  config.shared_context_metadata_behavior = :apply_to_host_groups
+
+# The settings below are suggested to provide a good initial experience
+# with RSpec, but feel free to customize to your heart's content.
+=begin
+  # This allows you to limit a spec run to individual examples or groups
+  # you care about by tagging them with `:focus` metadata. When nothing
+  # is tagged with `:focus`, all examples get run. RSpec also provides
+  # aliases for `it`, `describe`, and `context` that include `:focus`
+  # metadata: `fit`, `fdescribe` and `fcontext`, respectively.
+  config.filter_run_when_matching :focus
+
+  # Allows RSpec to persist some state between runs in order to support
+  # the `--only-failures` and `--next-failure` CLI options. We recommend
+  # you configure your source control system to ignore this file.
+  config.example_status_persistence_file_path = "spec/examples.txt"
+
+  # Limits the available syntax to the non-monkey patched syntax that is
+  # recommended. For more details, see:
+  # https://relishapp.com/rspec/rspec-core/docs/configuration/zero-monkey-patching-mode
+  config.disable_monkey_patching!
+
+  # Many RSpec users commonly either run the entire suite or an individual
+  # file, and it's useful to allow more verbose output when running an
+  # individual spec file.
+  if config.files_to_run.one?
+    # Use the documentation formatter for detailed output,
+    # unless a formatter has already been configured
+    # (e.g. via a command-line flag).
+    config.default_formatter = "doc"
+  end
+
+  # Print the 10 slowest examples and example groups at the
+  # end of the spec run, to help surface which specs are running
+  # particularly slow.
+  config.profile_examples = 10
+
+  # Run specs in random order to surface order dependencies. If you find an
+  # order dependency and want to debug it, you can fix the order by providing
+  # the seed, which is printed after each run.
+  #     --seed 1234
+  config.order = :random
+
+  # Seed global randomization in this process using the `--seed` CLI option.
+  # Setting this allows you to use `--seed` to deterministically reproduce
+  # test failures related to randomization by passing the same `--seed` value
+  # as the one that triggered the failure.
+  Kernel.srand config.seed
+=end
+end

data/examples/rails_app/spec/swagger_controller_spec.rb

@@ -0,0 +1,13 @@
+require 'rails_helper'
+
+RSpec.describe "SwaggerController", type: :request do
+  describe '生成 Swagger 文档' do
+    it "生成文档" do
+      get '/swagger_doc'
+      expect(response.status).to eq(200)
+
+      response_body = JSON.parse(response.body)
+      expect(response_body['paths']).not_to be_empty
+    end
+  end
+end

data/lib/meta/application/execution.rb

@@ -72,15 +72,7 @@ module Meta
 
     # 运行过程中首先会解析参数
     def parse_parameters(parameters_meta)
-      self.parameters = parameters_meta.map do |name, options|
-        schema = options[:schema]
-        value = if options[:in] == 'header'
-          schema.filter(request.get_header('HTTP_' + name.to_s.upcase.gsub('-', '_')))
-        else
-          schema.filter(request.params[name.to_s])
-        end
-        [name, value]
-      end.to_h.freeze
+      self.parameters = parameters_meta.filter(request).freeze
     end
 
     # parse_params 不再解析参数了，而只是设置 @params_schema，并清理父路由解析的变量
@@ -112,8 +104,8 @@ module Meta
       else
         # 渲染多键值结点
         new_hash = renders.map do |key, render_content|
-          schema = entity_schema.properties[key]
-          raise Errors::RenderingError, "渲染的键名 `#{key}` 不存在，请检查实体定义以确认是否有拼写错误" if schema.nil?
+          raise Errors::RenderingError, "渲染的键名 `#{key}` 不存在，请检查实体定义以确认是否有拼写错误" unless entity_schema.properties.key?(key)
+          schema = entity_schema.properties[key].schema(:render)
 
           filtered = schema.filter(render_content[:value], **render_content[:options], execution: self, stage: :render)
           [key, filtered]

data/lib/meta/application/{meta.rb → metadata.rb}

@@ -1,14 +1,15 @@
 # frozen_string_literal: true
+require_relative 'parameters'
 
 module Meta
-  class Meta
+  class Metadata
     attr_reader :title, :description, :tags, :parameters, :request_body, :responses
 
     def initialize(title: nil, description: nil, tags: [], parameters: {}, request_body: nil, responses: nil)
       @title = title
       @description = description
       @tags = tags
-      @parameters = parameters
+      @parameters = parameters.is_a?(Parameters) ? parameters : Parameters.new(parameters)
       @request_body = request_body
       @responses = responses || { 204 => nil }
     end
@@ -24,18 +25,7 @@ module Meta
       operation_object[:tags] = tags unless tags.empty?
       operation_object[:description] = description if description
 
-      operation_object[:parameters] = parameters.map do |name, options|
-        property_options = options[:schema].param_options
-        {
-          name: name,
-          in: options[:in],
-          required: property_options[:required] || nil,
-          description: property_options[:description] || '',
-          schema: {
-            type: property_options[:type]
-          }
-        }.compact
-      end unless parameters.empty?
+      operation_object[:parameters] = parameters.to_swagger_doc
 
       if request_body
         schema = request_body.to_schema_doc(stage: :param, schemas: schemas)
@@ -65,7 +55,7 @@ module Meta
     end
 
     def self.new(meta = {})
-      meta.is_a?(Meta) ? meta : super(**meta)
+      meta.is_a?(Metadata) ? meta : super(**meta)
     end
   end
 end

data/lib/meta/application/parameters.rb

@@ -0,0 +1,47 @@
+# 仅仅处理 URL、Query、Header 中的参数
+
+module Meta
+  class Parameters
+    extend Forwardable
+
+    attr_reader :parameters
+
+    def initialize(parameters)
+      @parameters = parameters
+    end
+
+    def filter(request)
+      parameters.map do |name, options|
+        schema = options[:schema]
+        value = if options[:in] == 'header'
+          schema.filter(request.get_header('HTTP_' + name.to_s.upcase.gsub('-', '_')))
+        else
+          schema.filter(request.params[name.to_s])
+        end
+        [name, value]
+      end.to_h
+    end
+
+    def to_swagger_doc
+      parameters.map do |name, options|
+        property_options = options[:schema].options
+        {
+          name: name,
+          in: options[:in],
+          required: property_options[:required] || nil,
+          description: property_options[:description] || '',
+          schema: {
+            type: property_options[:type]
+          }
+        }.compact
+      end unless parameters.empty?
+    end
+
+    def merge(parameters)
+      parameters_hash = parameters.is_a?(Parameters) ? parameters.parameters : parameters
+      Parameters.new(self.parameters.merge(parameters_hash))
+    end
+
+    def_delegators :parameters, :key?, :empty?
+  end
+end

data/lib/meta/application/route.rb

@@ -2,7 +2,7 @@
 
 require_relative 'execution'
 require_relative 'path_matching_mod'
-require_relative 'meta'
+require_relative 'metadata'
 
 module Meta
   class Route
@@ -13,7 +13,7 @@ module Meta
     def initialize(path: '', method: :all, meta: {}, actions: [])
       @path = Utils::Path.normalize_path(path)
       @method = method
-      @meta = Meta.new(meta)
+      @meta = Metadata.new(meta)
       @actions = actions
     end
 

data/lib/meta/json_schema/builders/array_schema_builder.rb

@@ -4,21 +4,22 @@ module Meta
   module JsonSchema
     class ArraySchemaBuilder
       def initialize(options, &block)
-        raise 'type 选项必须是 array' if !options[:type].nil? && options[:type] != 'array'
-
-        options = options.merge(type: 'array')
-        @options = options
-
-        items_options = options.delete(:items) || {}
-        if object_property?(items_options, block)
-          @items = ObjectSchemaBuilder.new(items_options, &block).to_schema
+        options = options.dup
+        if options[:items]
+          items_options = options.delete(:items)
+        elsif options[:ref]
+          items_options = { ref: options.delete(:ref) }
+        elsif options[:dynamic_ref]
+          items_options = { dynamic_ref: options.delete(:dynamic_ref) }
         else
-          @items = BaseSchema.new(items_options)
+          items_options = {}
         end
+        @items_schema = SchemaBuilderTool.build(items_options, &block)
+        @base_options = options
       end
 
       def to_schema
-        ArraySchema.new(@items, @options)
+        ArraySchema.new(@items_schema, @base_options)
       end
 
       def object_property?(options, block)

data/lib/meta/json_schema/builders/dynamic_schema_builder.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative '../schemas/dynamic_schema'
+
+module Meta
+  module JsonSchema
+    class DynamicSchemaBuilder
+      def initialize(options)
+        options = options.dup
+        @dynamic_schema_options = options.delete(:dynamic_ref)
+        @base_options = options
+      end
+
+      def to_schema
+        DynamicSchema.new(
+          @dynamic_schema_options[:resolve],
+          one_of: @dynamic_schema_options[:one_of] && @dynamic_schema_options[:one_of].map { |schema| RefSchema.new(schema.to_schema) },
+          **@base_options
+        )
+      end
+    end
+  end
+end

data/lib/meta/json_schema/builders/object_schema_builder.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative '../schemas/properties'
+
 module Meta
   module JsonSchema
     class ObjectSchemaBuilder
@@ -41,23 +43,7 @@ module Meta
       end
 
       def property(name, options = {}, &block)
-        name = name.to_sym
-        # REVIEW: 为何要 dup，删掉试试
-        options = options.dup
-
-        using = options[:using]
-        if using.respond_to?(:to_schema)
-          schema = using.to_schema
-          if options[:type] == 'array'
-            @properties[name] = ArraySchema.new(schema, options)
-          else
-            @properties[name] = schema.dup(options)
-          end
-        elsif using.is_a?(Proc) || using.is_a?(Hash) || using.nil?
-          @properties[name] = SchemaBuilderTool.build(options, &block)
-        else
-          raise "非法的 `using` 选项，应传递具有 `to_schema` 方法（如 Entity、Schema 等）或 Hash、Proc（动态生成 Schema）。当前传递：#{block}"
-        end
+        @properties[name.to_sym] = Properties.build_property(options, ->(options) { SchemaBuilderTool.build(options, &block) })
       end
 
       alias expose property
@@ -70,7 +56,7 @@ module Meta
       end
 
       def to_schema(locked_options = nil)
-        ObjectSchema.new(properties: @properties, object_validations: @validations, options: @options, locked_options: locked_options, schema_name_resolver: @schema_name_resolver)
+        ObjectSchema.new(properties: @properties, options: @options, locked_options: locked_options, schema_name_resolver: @schema_name_resolver)
       end
 
       def lock(key, value)

data/lib/meta/json_schema/builders/ref_schema_builder.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative '../schemas/ref_schema'
+
+module Meta
+  module JsonSchema
+    class RefSchemaBuilder
+      def initialize(options)
+        options = options.dup
+        @ref_schema_builder = options.delete(:ref)
+        @base_options = options
+      end
+
+      def to_schema
+        RefSchema.new(@ref_schema_builder.to_schema, @base_options)
+      end
+    end
+  end
+end

data/lib/meta/json_schema/builders/schema_builder_tool.rb

@@ -1,12 +1,29 @@
 # frozen_string_literal: true
 
+require_relative 'ref_schema_builder'
+require_relative 'dynamic_schema_builder'
+require_relative 'array_schema_builder'
+require_relative 'object_schema_builder'
+
 module Meta
   module JsonSchema
     class SchemaBuilderTool
       class << self
+        SCHEMA_BUILDER_OPTIONS = Utils::KeywordArgs::Builder.build do
+          permit_extras true
+
+          key :ref, alias_names: [:using]
+          key :dynamic_ref, alias_names: [:dynamic_using], normalizer: ->(value) { value.is_a?(Proc) ? { resolve: value } : value }
+        end
         def build(options = {}, &block)
+          options = SCHEMA_BUILDER_OPTIONS.check(options)
+
           if apply_array_schema?(options, block)
             ArraySchemaBuilder.new(options, &block).to_schema
+          elsif apply_ref_schema?(options, block)
+            RefSchemaBuilder.new(options).to_schema
+          elsif apply_dynamic_schema?(options, block)
+            DynamicSchemaBuilder.new(options).to_schema
           elsif apply_object_schema?(options, block)
             ObjectSchemaBuilder.new(options, &block).to_schema
           else
@@ -17,12 +34,20 @@ module Meta
         private
 
         def apply_array_schema?(options, block)
-          options[:type] == 'array' && (options[:items] || block)
+          options[:type] == 'array' && (options[:items] || options[:ref] || options[:dynamic_ref] || block)
         end
 
         def apply_object_schema?(options, block)
           (options[:type] == 'object' || options[:type].nil?) && (options[:properties] || block)
         end
+
+        def apply_ref_schema?(options, block)
+          options[:ref] != nil
+        end
+
+        def apply_dynamic_schema?(options, block)
+          options[:dynamic_ref] != nil
+        end
       end
     end
   end

data/lib/meta/json_schema/schemas/array_schema.rb

@@ -25,12 +25,12 @@ module Meta
         end
       end
 
-      def to_schema_doc(user_options = {})
-        stage_options = user_options[:stage] == :param ? @param_options : @render_options
+      def to_schema_doc(**user_options)
+        stage_options = options
 
         schema = {
           type: 'array',
-          items: @items ? @items.to_schema_doc(user_options) : {}
+          items: @items ? @items.to_schema_doc(**user_options) : {}
         }
         schema[:description] = stage_options[:description] if stage_options[:description]
         schema

data/lib/meta/json_schema/schemas/base_schema.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative '../../utils/kwargs/check'
 require_relative '../support/schema_options'
 
 module Meta
@@ -12,63 +13,30 @@ module Meta
       # `options` 属性都是描述该对象的本身，而不是深层的属性。
       #
       # 较常出现错误的是数组，`options` 是描述数组的，而不是描述数组内部元素的。
-      attr_reader :param_options, :render_options
+      attr_reader :options
 
-      # 传递 path 参数主要是为了渲染 Parameter 文档时需要
       def initialize(options = {})
-        @param_options, @render_options = SchemaOptions.normalize_to_param_and_render(options)
+        @options = SchemaOptions.normalize(options)
       end
 
-      def options(stage, key = nil)
-        stage_options = case stage 
-                        when :param 
-                          param_options
-                        when :render
-                          render_options
-                        when nil
-                          merged_options
-                        else
-                          raise "非法的 stage 参数，它只允许取值 :param、:render 或 nil，却收到 #{stage.inspect}"
-                        end
-        if key
-          stage_options ? stage_options[key] : nil
-        else
-          stage_options
-        end
-      end
+      USER_OPTIONS_CHECKER = Utils::KeywordArgs::Builder.build do
+        key :stage, :execution, :object_value, :type_conversion, :validation
 
-      # 将 params 和 render 的选项合并
-      def merged_options
-        (param_options || {}).merge(render_options || {})
+        # 以下三个是 ObjectSchema 需要的选项
+        key :discard_missing, :exclude, :scope
       end
 
       def filter(value, user_options = {})
-        user_options = Utils::KeywordArgs.check(
-          args: user_options,
-          schema: {
-            stage: nil,
-            execution: nil,
-            object_value: nil,
-            type_conversion: true,
-            validation: true,
-
-            # 以下三个是 ObjectSchema 需要的选项
-            discard_missing: false,
-            exclude: [],
-            scope: []
-          }
-        )
-
-        stage_options = options(user_options[:stage])
-
-        value = resolve_value(user_options) if stage_options[:value]
-        value = JsonSchema::Presenters.present(stage_options[:presenter], value) if stage_options[:presenter]
-        value = stage_options[:default] if value.nil? && stage_options.key?(:default)
-        value = stage_options[:convert].call(value) if stage_options[:convert]
+        user_options = USER_OPTIONS_CHECKER.check(user_options)
+
+        value = resolve_value(user_options) if options[:value]
+        value = JsonSchema::Presenters.present(options[:presenter], value) if options[:presenter]
+        value = options[:default] if value.nil? && options.key?(:default)
+        value = options[:convert].call(value) if options[:convert]
 
         # 第一步，转化值。
         # 需要注意的是，对象也可能被转换，因为并没有深层次的结构被声明。
-        type = stage_options[:type]
+        type = options[:type]
         unless user_options[:type_conversion] == false || type.nil? || value.nil?
           begin
             value = JsonSchema::TypeConverter.convert_value(value, type)
@@ -78,23 +46,17 @@ module Meta
         end
 
         # 第二步，做校验。
-        validate!(value, stage_options) unless user_options[:validation] == false
-
-        # 第三步，如果使用了 using 块，需要进一步解析
-        if stage_options[:using] && stage_options[:using].is_a?(Hash)
-          schema = stage_options[:using][:resolve].call(value).to_schema
-          value = schema.filter(value, user_options)
-        end
+        validate!(value, options) unless user_options[:validation] == false
 
         value
       end
 
-      def value?(stage)
-        options(stage, :value) != nil
+      def value?
+        options[:value] != nil
       end
 
       def resolve_value(user_options)
-        value_proc = options(user_options[:stage], :value)
+        value_proc = options[:value]
         value_proc_params = (value_proc.lambda? && value_proc.arity == 0) ?  [] : [user_options[:object_value]]
 
         if user_options[:execution]
@@ -104,21 +66,19 @@ module Meta
         end
       end
 
-      def to_schema_doc(user_options = {})
-        stage_options = options(user_options[:stage])
-
-        return Presenters.to_schema_doc(stage_options[:presenter], stage_options) if stage_options[:presenter]
+      # 生成 Swagger 文档的 schema 格式。
+      #
+      # 选项：
+      # - stage: 传递 :param 或 :render
+      # - schemas: 用于保存已经生成的 Schema
+      # - presenter: 兼容 Grape 框架的实体类
+      def to_schema_doc(**user_options)
+        return Presenters.to_schema_doc(options[:presenter], options) if options[:presenter]
 
         schema = {}
-        schema[:type] = stage_options[:type] if stage_options[:type]
-        schema[:description] = stage_options[:description] if stage_options[:description]
-        schema[:enum] = stage_options[:allowable] if stage_options[:allowable]
-        if stage_options[:using] && stage_options[:using].is_a?(Hash)
-          using_options = stage_options[:using]
-          schema[:oneOf] = using_options[:one_of].map do |schema|
-            schema.to_schema.to_schema_doc(user_options)
-          end if using_options[:one_of]
-        end
+        schema[:type] = options[:type] if options[:type]
+        schema[:description] = options[:description] if options[:description]
+        schema[:enum] = options[:allowable] if options[:allowable]
 
         schema
       end

data/lib/meta/json_schema/schemas/dynamic_schema.rb

@@ -0,0 +1,29 @@
+require_relative 'base_schema'
+
+module Meta
+  module JsonSchema
+    class DynamicSchema < BaseSchema
+      def initialize(resolver, one_of: nil, **base_options)
+        super(base_options)
+
+        @resolver = resolver
+        @one_of = one_of
+      end
+
+      def filter(value, user_options = {})
+        value = super(value, user_options)
+        schema = @resolver.call(value).to_schema
+        schema.filter(value, user_options)
+      end
+
+      def to_schema_doc(user_options)
+        schema = { type: 'object' }
+        schema[:oneOf] = @one_of.map do |schema|
+          schema.to_schema_doc(user_options)
+        end if @one_of
+
+        schema
+      end
+    end
+  end
+end