meta-api 0.0.7 → 0.0.9

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

@@ -5,65 +5,6 @@ require 'forwardable'
 module Meta
   module JsonSchema
     class Properties
-      class StagingProperty
-        def initialize(param:, render:, none:)
-          @param_stage = param
-          @render_stage = render
-          @none_stage = none
-        end
-
-        def stage(stage = nil)
-          case stage
-          when :param
-            @param_stage
-          when :render
-            @render_stage
-          else
-            @none_stage
-          end
-        end
-
-        def stage?(stage)
-          stage(stage) != nil
-        end
-
-        def schema(stage = nil)
-          stage(stage).schema
-        end
-
-        def self.build(options, build_schema)
-          param_opts, render_opts, common_opts = SchemaOptions.divide_to_param_and_render(options)
-
-          StagingProperty.new(
-            param: options[:param] === false ? nil : ScopingProperty.build(param_opts, build_schema),
-            render: options[:render] === false ? nil : ScopingProperty.build(render_opts, build_schema),
-            none: ScopingProperty.build(common_opts, build_schema)
-          )
-        end
-      end
-
-      class ScopingProperty
-        attr_reader :scope, :schema
-
-        def initialize(scope: :all, schema:)
-          scope = :all if scope.nil?
-          scope = [scope] unless scope.is_a?(Array) || scope == :all
-          if scope.is_a?(Array) && scope.any? { |s| s.is_a?(Integer) }
-            raise ArgumentError, 'scope 选项内不可传递数字'
-          end
-          @scope = scope
-
-          @schema = schema
-        end
-
-        def self.build(options, build_schema)
-          options = options.dup
-          scope = options.delete(:scope)
-          schema = build_schema.call(options)
-          ScopingProperty.new(scope: scope, schema: schema)
-        end
-      end
-
       extend Forwardable
 
       def initialize(properties)
@@ -77,13 +18,16 @@ module Meta
         user_scope = user_options[:scope] || [0]
         exclude = user_options.delete(:exclude) # 这里删除 exclude 选项，不要传递给下一层
         properties = filter_by(stage: stage, user_scope: user_scope)
-        filtered_properties = properties.filter do |name, property|
+        filtered_properties = properties.filter do |name, property_schema|
           # 通过 discard_missing 过滤
           next false if user_options[:discard_missing] && !object_value.key?(name.to_s)
 
           # 通过 locked_exclude 选项过滤
           next false if exclude && exclude.include?(name)
 
+          # 通过 if 选项过滤
+          next false unless property_schema.if?(user_options)
+
           # 默认返回 true
           next true
         end
@@ -91,12 +35,14 @@ module Meta
         # 第二步，递归过滤每一个属性
         object = {}
         errors = {}
+        cause = nil
         filtered_properties.each do |name, property_schema|
           value = resolve_property_value(object_value, name, property_schema)
 
           begin
             object[name] = property_schema.filter(value, **user_options, object_value: object_value)
           rescue JsonSchema::ValidationErrors => e
+            cause = e.cause || e if cause.nil? # 将第一次出现的错误作为 cause
             errors.merge! e.prepend_root(name).errors
           end
         end.to_h
@@ -108,18 +54,25 @@ module Meta
 
         if errors.empty?
           object
+        elsif cause
+          begin
+            raise cause
+          rescue
+            raise JsonSchema::ValidationErrors.new(errors)
+          end
         else
           raise JsonSchema::ValidationErrors.new(errors)
         end
       end
 
-      def to_swagger_doc(locked_scopes:, stage:, **user_options)
+      def to_swagger_doc(scope: [], stage: nil, **user_options)
+        locked_scopes = scope
         properties = filter_by(stage: stage, user_scope: locked_scopes)
         required_keys = properties.filter do |key, property_schema|
           property_schema.options[:required]
         end.keys
         properties = properties.transform_values do |property_schema |
-          property_schema.to_schema_doc(stage: stage, **user_options)
+          property_schema.to_schema_doc(stage: stage, scope: scope, **user_options)
         end
         [properties, required_keys]
       end
@@ -132,23 +85,16 @@ module Meta
       end
 
       def self.build_property(*args)
-        StagingProperty.build(*args)
+        StagingSchema.build_from_options(*args)
       end
 
       private
 
       def filter_by(stage:, user_scope: false)
-        properties = @properties.filter do |name, property|
-          # 通过 stage 过滤。
-          next false unless property.stage?(stage)
-          property = property.stage(stage)
-
-          # 通过 user_scope 过滤
-          next true if property.scope == :all
-          (user_scope - property.scope).empty? # user_scope 应被消耗殆尽
-        end
-        properties.transform_values do |property|
-          property.stage(stage).schema
+        @properties.transform_values do |property|
+          property.find_schema(stage: stage, scope: user_scope)
+        end.filter do |name, schema|
+          schema.filter?
         end
       end
 

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

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Meta
+  module JsonSchema
+    class ScopingSchema < BaseSchema
+      attr_reader :on, :schema
+
+      def initialize(required_scope: [], schema:)
+        raise ArgumentError, 'required_scope 选项不可传递 nil' if required_scope.nil?
+        required_scope = [required_scope] unless required_scope.is_a?(Array)
+
+        @on = required_scope
+        @schema = schema
+      end
+
+      def scoped(user_scopes)
+        return schema if (on - user_scopes).empty? # required_scopes 应被消耗殆尽
+
+        UnsupportedSchema.new(:on, user_scopes)
+      end
+
+      STAGING_SCHEMA_OPTIONS = Utils::KeywordArgs::Builder.build do
+        permit_extras true
+
+        # TODO: 如果我想把 on 改名为 require_scopes，关键字参数的机制是否支持？
+        key :on, alias_names: [:scope], default: [], normalizer: ->(required_scopes) {
+          required_scopes = [] if required_scopes.nil?
+          required_scopes = [required_scopes] unless required_scopes.is_a?(Array)
+          required_scopes
+        }
+      end
+      def self.build_from_options(options, build_schema)
+        options = STAGING_SCHEMA_OPTIONS.check(options)
+        required_scope = options.delete(:on) || []
+        schema = build_schema.call(options)
+        schema = ScopingSchema.new(required_scope: required_scope, schema: schema) unless required_scope.empty?
+        schema
+      end
+    end
+  end
+end

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

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require_relative '../../utils/kwargs/check'
+require_relative '../support/schema_options'
+require_relative 'scoping_schema'
+require_relative 'unsupported_schema'
+
+module Meta
+  module JsonSchema
+    # 内含 param_schema, render_schema, default_schema，分别用于不同的阶段。
+    class StagingSchema < BaseSchema
+      attr_reader :param_schema, :render_schema, :default_schema
+
+      def initialize(param_schema:, render_schema:, default_schema:)
+        raise ArgumentError, 'param_schema 选项重复提交为 StagingSchema' if param_schema.is_a?(StagingSchema)
+        raise ArgumentError, 'render_schema 选项重复提交为 StagingSchema' if render_schema.is_a?(StagingSchema)
+        raise ArgumentError, 'default_schema 选项重复提交为 StagingSchema' if default_schema.is_a?(StagingSchema)
+
+        @param_schema = param_schema
+        @render_schema = render_schema
+        @default_schema = default_schema
+      end
+
+      def filter(value, user_options = {})
+        if user_options[:stage] == :param
+          param_schema.filter(value, user_options)
+        elsif user_options[:stage] == :render
+          render_schema.filter(value, user_options)
+        else
+          default_schema.filter(value, user_options)
+        end
+      end
+
+      def staged(stage)
+        if stage == :param
+          param_schema
+        elsif stage == :render
+          render_schema
+        else
+          default_schema
+        end
+      end
+
+      def self.build_from_options(options, build_schema = ->(opts) { BaseSchema.new(opts) })
+        param_opts, render_opts, common_opts = SchemaOptions.divide_to_param_and_render(options)
+        if param_opts == common_opts && render_opts == common_opts
+          return ScopingSchema.build_from_options(common_opts, build_schema)
+        else
+          StagingSchema.new(
+            param_schema: param_opts ? ScopingSchema.build_from_options(param_opts, build_schema) : UnsupportedSchema.new(:stage, :param),
+            render_schema: render_opts ? ScopingSchema.build_from_options(render_opts, build_schema) : UnsupportedSchema.new(:stage, :render),
+            default_schema: ScopingSchema.build_from_options(common_opts, build_schema),
+            )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Meta
+  module JsonSchema
+    class UnsupportedSchema < BaseSchema
+      attr_reader :key, :value
+
+      def initialize(key, value)
+        @key = key
+        @value = value
+      end
+
+      def filter?
+        false
+      end
+
+      def filter(value, options)
+        raise UnsupportedError, "不支持的 #{key}: #{value}}"
+      end
+    end
+  end
+end

data/lib/meta/json_schema/support/errors.rb

@@ -34,5 +34,8 @@ module Meta
         errors['']
       end
     end
+
+    class UnsupportedError < StandardError
+    end
   end
 end

data/lib/meta/json_schema/support/schema_options.rb

@@ -9,11 +9,6 @@ module Meta
         scope: [],
         required: false
       }
-      @allowable_options = (
-        %i[type description in value using default presenter convert scope items using] +
-        @default_options.keys + 
-        JsonSchema::Validators.keys
-      ).uniq
 
       class << self
         def divide_to_param_and_render(options)
@@ -37,10 +32,6 @@ module Meta
             end
           end
 
-          # 处理 validators
-          unknown_validators = options.keys - @allowable_options
-          raise "未知的选项：#{unknown_validators.join(', ')}" unless unknown_validators.empty?
-
           options
         end
 

data/lib/meta/route_dsl/meta_builder.rb

@@ -9,7 +9,7 @@ module Meta
       def initialize(route_full_path:, route_method: :all, &block)
         @route_full_path = route_full_path
         @method = route_method
-        @meta = {}
+        @meta = { scope: [] }
         @parameters_builder = ParametersBuilder.new(route_full_path: route_full_path, route_method: route_method) # 默认给一个空的参数构建器，它只会处理 path 参数
 
         instance_exec &block if block_given?
@@ -43,7 +43,7 @@ module Meta
         codes.each { |code| @meta[:responses][code] = entity_schema }
       end
 
-      [:tags, :title, :description].each do |method_name|
+      [:tags, :title, :description, :scope].each do |method_name|
         define_method(method_name) do |value|
           @meta[method_name] = value
         end

data/lib/meta/route_dsl/uniformed_params_builder.rb

@@ -15,16 +15,16 @@ module Meta
 
       def param(name, options = {}, &block)
         options = (options || {}).dup
-        in_op = options.delete(:in) || \
           if path_param_names.include?(name)
-            'path'
+            options = Utils::KeywordArgs::Checker.fix!(options, in: 'path', required: true)
           elsif @route_method == :get
-            'query'
+            options = Utils::KeywordArgs::Checker.merge_defaults!(options, in: 'query')
           else
-            'body'
+            options = Utils::KeywordArgs::Checker.merge_defaults!(options, in: 'body')
           end
 
-        if in_op == 'body'
+        if options[:in] == 'body'
+          options.delete(:in)
           property name, options, &block
         else
           @parameters_builder.param name, options

data/lib/meta/swagger_doc.rb

@@ -32,7 +32,7 @@ module Meta
 
       # 生成单个路由的文档
       def generate_operation_object(route, schemas)
-        route.meta.generate_operation_doc(schemas)
+        route.generate_operation_doc(schemas)
       end
 
       private

data/lib/meta/utils/kwargs/builder.rb

@@ -58,6 +58,7 @@ module Meta
         def initialize(name:, normalizer: DEFAULT_TRANSFORMER, validator: nil, default: nil, alias_names: [])
           @key_name = name
           @consumer_names = [name] + alias_names
+          # TODO: 当且仅当 value 是 nil 时，才使用 default
           @normalizer = default ? ->(value) { normalizer.call(value || default) } : normalizer
           @validator = validator
         end
@@ -70,6 +71,7 @@ module Meta
         end
 
         def consume_name(final_args, args, consumer_name)
+          # TODO: default 未起作用
           if args.key?(consumer_name)
             value = @normalizer.call(args.delete(consumer_name))
             @validator.call(value) if @validator

data/lib/meta/utils/route_dsl_builders.rb

@@ -15,6 +15,7 @@ module Meta
           if options1[:responses] && options2[:responses]
             final_options[:responses] = options1[:responses].merge(options2[:responses])
           end
+          final_options[:scope] = [options1[:scope] || [], options2[:scope] || []].flatten.uniq
           final_options
         end
 

data/meta-api.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |spec|
   spec.name          = "meta-api"
-  spec.version       = "0.0.7"
+  spec.version       = "0.0.9"
   spec.authors       = ["yetrun"]
   spec.email         = ["yetrun@foxmail.com"]
 
@@ -14,10 +14,11 @@ Gem::Specification.new do |spec|
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = "https://github.com/yetrun/web-frame.git"
 
+  spec.add_dependency "hash_to_struct", "~> 1.0.0"
+
   # Specify which files should be added to the gem when it is released.
-  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
-  spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
-    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
-  end
+  spec.files = Dir.glob("{config,lib}/{.rb,/**/*}", File::FNM_DOTMATCH).reject {|f| File.directory?(f) }
+  spec.files += %w[CHANGELOG.md LICENSE.txt meta-api.gemspec]
+
   spec.require_paths = ["lib"]
 end

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: meta-api
 version: !ruby/object:Gem::Version
-  version: 0.0.7
+  version: 0.0.9
 platform: ruby
 authors:
 - yetrun
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-07-14 00:00:00.000000000 Z
-dependencies: []
+date: 2023-07-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: hash_to_struct
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.0.0
 description: 一个 Web API 框架，该框架采用定义元信息的方式编写 API，并同步生成 API 文档
 email:
 - yetrun@foxmail.com
@@ -17,112 +31,58 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".autoenv.zsh"
-- ".gitignore"
-- ".rubocop.yml"
 - CHANGELOG.md
-- Gemfile
-- Gemfile.lock
 - LICENSE.txt
-- README.md
-- Rakefile
-- config/locales/zh-CN.yml
-- docs/Rails.md
-- docs/名称由来.md
-- docs/如何贡献.md
-- docs/教程.md
-- docs/索引.md
-- examples/lobster.rb
-- examples/rack_app/README.md
-- examples/rack_app/config.ru
-- examples/rack_app/hello.rb
-- examples/rack_app/timing.rb
-- examples/rails_app/.gitattributes
-- examples/rails_app/.gitignore
-- examples/rails_app/.rspec
-- examples/rails_app/.ruby-version
-- examples/rails_app/Gemfile
-- examples/rails_app/Gemfile.lock
-- examples/rails_app/README.md
-- examples/rails_app/Rakefile
-- examples/rails_app/app/controllers/application_controller.rb
-- examples/rails_app/app/controllers/concerns/.keep
-- examples/rails_app/app/controllers/data_controller.rb
-- examples/rails_app/app/controllers/swagger_controller.rb
-- examples/rails_app/app/models/concerns/.keep
-- examples/rails_app/bin/rails
-- examples/rails_app/bin/rake
-- examples/rails_app/bin/setup
-- examples/rails_app/config.ru
-- examples/rails_app/config/application.rb
-- examples/rails_app/config/boot.rb
-- examples/rails_app/config/credentials.yml.enc
-- examples/rails_app/config/environment.rb
-- examples/rails_app/config/environments/development.rb
-- examples/rails_app/config/environments/production.rb
-- examples/rails_app/config/environments/test.rb
-- examples/rails_app/config/initializers/cors.rb
-- examples/rails_app/config/initializers/filter_parameter_logging.rb
-- examples/rails_app/config/initializers/inflections.rb
-- examples/rails_app/config/initializers/meta_rails_plugin.rb
-- examples/rails_app/config/locales/en.yml
-- examples/rails_app/config/puma.rb
-- examples/rails_app/config/routes.rb
-- examples/rails_app/lib/tasks/.keep
-- examples/rails_app/log/.keep
-- examples/rails_app/public/robots.txt
-- examples/rails_app/spec/data_controller_spec.rb
-- examples/rails_app/spec/rails_helper.rb
-- examples/rails_app/spec/spec_helper.rb
-- examples/rails_app/spec/swagger_controller_spec.rb
-- examples/rails_app/tmp/.keep
-- examples/rails_app/tmp/pids/.keep
-- lib/meta/api.rb
-- lib/meta/application.rb
-- lib/meta/application/application.rb
-- lib/meta/application/execution.rb
-- lib/meta/application/linked_action.rb
-- lib/meta/application/metadata.rb
-- lib/meta/application/parameters.rb
-- lib/meta/application/path_matching_mod.rb
-- lib/meta/application/route.rb
-- lib/meta/config.rb
-- lib/meta/entity.rb
-- lib/meta/errors.rb
-- lib/meta/json_schema.rb
-- lib/meta/json_schema/builders/array_schema_builder.rb
-- lib/meta/json_schema/builders/dynamic_schema_builder.rb
-- lib/meta/json_schema/builders/object_schema_builder.rb
-- lib/meta/json_schema/builders/ref_schema_builder.rb
-- lib/meta/json_schema/builders/schema_builder_tool.rb
-- lib/meta/json_schema/schemas.rb
-- lib/meta/json_schema/schemas/array_schema.rb
-- lib/meta/json_schema/schemas/base_schema.rb
-- lib/meta/json_schema/schemas/dynamic_schema.rb
-- lib/meta/json_schema/schemas/object_schema.rb
-- lib/meta/json_schema/schemas/properties.rb
-- lib/meta/json_schema/schemas/ref_schema.rb
-- lib/meta/json_schema/support/errors.rb
-- lib/meta/json_schema/support/presenters.rb
-- lib/meta/json_schema/support/schema_options.rb
-- lib/meta/json_schema/support/type_converter.rb
-- lib/meta/json_schema/support/validators.rb
-- lib/meta/load_i18n.rb
-- lib/meta/rails.rb
-- lib/meta/route_dsl/action_builder.rb
-- lib/meta/route_dsl/application_builder.rb
-- lib/meta/route_dsl/around_action_builder.rb
-- lib/meta/route_dsl/chain_builder.rb
-- lib/meta/route_dsl/meta_builder.rb
-- lib/meta/route_dsl/parameters_builder.rb
-- lib/meta/route_dsl/route_builder.rb
-- lib/meta/route_dsl/uniformed_params_builder.rb
-- lib/meta/swagger_doc.rb
-- lib/meta/utils/kwargs/builder.rb
-- lib/meta/utils/kwargs/check.rb
-- lib/meta/utils/kwargs/checker.rb
-- lib/meta/utils/path.rb
-- lib/meta/utils/route_dsl_builders.rb
+- config//locales/zh-CN.yml
+- lib//meta/api.rb
+- lib//meta/application.rb
+- lib//meta/application/application.rb
+- lib//meta/application/execution.rb
+- lib//meta/application/linked_action.rb
+- lib//meta/application/metadata.rb
+- lib//meta/application/parameters.rb
+- lib//meta/application/path_matching_mod.rb
+- lib//meta/application/route.rb
+- lib//meta/config.rb
+- lib//meta/entity.rb
+- lib//meta/errors.rb
+- lib//meta/json_schema.rb
+- lib//meta/json_schema/builders/array_schema_builder.rb
+- lib//meta/json_schema/builders/dynamic_schema_builder.rb
+- lib//meta/json_schema/builders/object_schema_builder.rb
+- lib//meta/json_schema/builders/ref_schema_builder.rb
+- lib//meta/json_schema/builders/schema_builder_tool.rb
+- lib//meta/json_schema/schemas.rb
+- lib//meta/json_schema/schemas/array_schema.rb
+- lib//meta/json_schema/schemas/base_schema.rb
+- lib//meta/json_schema/schemas/dynamic_schema.rb
+- lib//meta/json_schema/schemas/object_schema.rb
+- lib//meta/json_schema/schemas/properties.rb
+- lib//meta/json_schema/schemas/ref_schema.rb
+- lib//meta/json_schema/schemas/scoping_schema.rb
+- lib//meta/json_schema/schemas/staging_schema.rb
+- lib//meta/json_schema/schemas/unsupported_schema.rb
+- lib//meta/json_schema/support/errors.rb
+- lib//meta/json_schema/support/presenters.rb
+- lib//meta/json_schema/support/schema_options.rb
+- lib//meta/json_schema/support/type_converter.rb
+- lib//meta/json_schema/support/validators.rb
+- lib//meta/load_i18n.rb
+- lib//meta/rails.rb
+- lib//meta/route_dsl/action_builder.rb
+- lib//meta/route_dsl/application_builder.rb
+- lib//meta/route_dsl/around_action_builder.rb
+- lib//meta/route_dsl/chain_builder.rb
+- lib//meta/route_dsl/meta_builder.rb
+- lib//meta/route_dsl/parameters_builder.rb
+- lib//meta/route_dsl/route_builder.rb
+- lib//meta/route_dsl/uniformed_params_builder.rb
+- lib//meta/swagger_doc.rb
+- lib//meta/utils/kwargs/builder.rb
+- lib//meta/utils/kwargs/check.rb
+- lib//meta/utils/kwargs/checker.rb
+- lib//meta/utils/path.rb
+- lib//meta/utils/route_dsl_builders.rb
 - meta-api.gemspec
 homepage: https://github.com/yetrun/web-frame
 licenses:
@@ -131,7 +91,7 @@ metadata:
   allowed_push_host: https://rubygems.org
   homepage_uri: https://github.com/yetrun/web-frame
   source_code_uri: https://github.com/yetrun/web-frame.git
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -146,8 +106,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.15
-signing_key: 
+rubygems_version: 3.3.26
+signing_key:
 specification_version: 4
 summary: 一个 Web API 框架
 test_files: []

data/.autoenv.zsh

@@ -1 +0,0 @@
-alias rspec="bundle exec rspec"

data/.gitignore

@@ -1,7 +0,0 @@
-.DS_Store
-*.gem
-.idea
-.ruby-version
-
-.bundle
-vendor