meta-api 0.0.8 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6b35c78915baab28213ceb9f2b6184c8ae177742ce0524529c681132fa6e0390
-  data.tar.gz: bc4ca96b46e0284f10fa41360ef4308aa7378121ead9f0cd1a536ac027cd590e
+  metadata.gz: bf3fb639df71a5353328e898711c9758c5e5fd3dd1760409ae823fbd0a7852e2
+  data.tar.gz: ea5dd728c3691fcf542d1085fd21d787d727c97b588652de3ffdd53b67512437
 SHA512:
-  metadata.gz: c5cf6b6c1ee9ba5af2826b6682e57a357bbd74caf7807a5f3f9cbd124b99bdce4bcc7cba7040b45b2c1d62b9abfda1e4ee6c47853c2ebcb57bfd2d8a224db622
-  data.tar.gz: 5043cc4c8516d7c6bc827d32889e26a2164299ba0a71b1439bd1594aabdd1975bbd1994139fed2ffca93409e9c1f2118157301b3cef502767750c52b061c7367
+  metadata.gz: 4a9f0a02d8091f77e7f9c2ea0ea67b86f1877327a7b75a7f4342fecd7f2822f9bde2ded59c20cb1c3227eb88a4b6b098c9438710a6a8eedcf4c8defb2f37c572
+  data.tar.gz: 2e7911858914bd1b34ff60007f48757f6afb1183c59d15d9e490fb5fe781244522d5500251dcbdbb02fc5f26a17d48ab82bbc2f6dd4368c2540f97bb351f6da3

data/CHANGELOG.md

@@ -1,5 +1,27 @@
 # 更新日志
 
+## 0.1.0（2023 年 8 月 5 日）
+
+1. 删除 `on:` 选项。
+2. `type_conversion` 为 `false` 时不影响对象和数组类型的转化。
+3. 修复 `ref:` 嵌套造成的文档问题。
+4. 将 HTTP Method 的 scope 添加 `$` 符号前缀，如 `$get`、`$post` 等。
+5. `Meta.config` 去掉了 `default_locked_scope` 的配置项。
+
+## 0.0.9（2023 年 7 月 22 日）
+
+1. JsonSchema 添加 before:、after: 选项，用于在过滤前后执行一些操作。
+2. 新添加一个 if: 选项用在属性上，它能够作为一个条件，当条件为 false 时，该属性不会被包含在结果内。
+3. 属性的 scope: 选项改名为 on: 选项。
+4. MetaBuilder 添加一个 scope 宏。
+5. Meta.config 的 JsonSchema 相关配置项改名。
+6. 优化异常的捕获。
+
+## 0.0.8（2023 年 7 月 17 日）
+
+1. `Meta.config` 添加 `initialize_configuration` 方法，用于接受若干个 Hash 初始化配置。
+2. 修复 GET 请求下会将 `header` 参数覆盖为 `query` 参数的 bug.
+
 ## 0.0.7（2023 年 7 月 14 日）
 
 1. 定义 parameters 宏时能够自动识别 `path` 参数。

data/lib/meta/application/execution.rb

@@ -4,8 +4,8 @@ require 'rack'
 
 module Meta
   class Execution
-    attr_reader :request, :response, :params_schema, :request_body_schema
-    attr_accessor :parameters
+    attr_reader :request, :response
+    attr_accessor :route_meta
 
     def initialize(request)
       @request = request
@@ -13,6 +13,10 @@ module Meta
       @parameters = {}
     end
 
+    def parameters
+      @_parameters || @_parameters = route_meta.parse_parameters(self)
+    end
+
     # 调用方式：
     #
     # - `request_body`：等价于 request_body(:keep_missing)
@@ -23,9 +27,9 @@ module Meta
 
       case mode
       when :keep_missing
-        @_request_body[:keep_missing] || @_request_body[:keep_missing] = parse_request_body_for_replacing.freeze
+        @_request_body[:keep_missing] || @_request_body[:keep_missing] = route_meta.parse_request_body(self).freeze
       when :discard_missing
-        @_request_body[:discard_missing] || @_request_body[:discard_missing] = parse_request_body_for_updating.freeze
+        @_request_body[:discard_missing] || @_request_body[:discard_missing] = route_meta.parse_request_body(self, discard_missing: true).freeze
       else
         raise NameError, "未知的 mode 参数：#{mode}"
       end
@@ -45,7 +49,7 @@ module Meta
         @_params[:raw] = parse_raw_params.freeze
       else
         params = parameters
-        params = params.merge(request_body(mode) || {}) if @request_body_schema
+        params = params.merge(request_body(mode) || {}) if route_meta.request_body
         @_params[mode] = params
       end
 
@@ -67,16 +71,14 @@ module Meta
       end
 
       @renders ||= {}
-      @renders[key] = { value: value, options: options || {} }
-    end
-
-    # 运行过程中首先会解析参数
-    def parse_parameters(parameters_meta)
-      self.parameters = parameters_meta.filter(request).freeze
-    end
+      raise '同一种 render 方式只能调用一次，请检查是否重复使用相同的 key 渲染，或者重复调用 render(value) 的方式' if @renders.key?(key)
+      if key == :__root__ && @renders.keys.any? { |key| key != :__root__ }
+        raise '已使用 render(:key, value) 的方式调用过，不能再使用 render(value) 的方式'
+      elsif key != :__root__ && @renders.key?(:__root__)
+        raise '已使用 render(value) 的方式调用过，不能再使用 render(:key, value) 的方式'
+      end
 
-    def parse_request_body(schema)
-      @request_body_schema = schema
+      @renders[key] = { value: value, options: options || {} }
     end
 
     def render_entity(entity_schema)
@@ -94,12 +96,7 @@ module Meta
           options = {}
         end
 
-        new_hash = entity_schema.filter(hash,
-          **Meta.config.json_schema_user_options,
-          **Meta.config.json_schema_render_stage_options,
-          **options,
-          execution: self, stage: :render
-        )
+        new_hash = route_meta.render_entity(self, entity_schema, hash, options)
         response.content_type = 'application/json' if response.content_type.nil?
         response.body = [JSON.generate(new_hash)]
       else
@@ -108,13 +105,8 @@ module Meta
         final_value = {}
         renders.each do |key, render_content|
           raise Errors::RenderingError, "渲染的键名 `#{key}` 不存在，请检查实体定义以确认是否有拼写错误" unless entity_schema.properties.key?(key)
-          schema = entity_schema.properties[key].schema(:render)
-          final_value[key] = schema.filter(render_content[:value],
-            **Meta.config.json_schema_user_options,
-            **Meta.config.json_schema_render_stage_options,
-            **render_content[:options],
-            execution: self, stage: :render
-          )
+          schema = entity_schema.properties[key].staged(:render)
+          final_value[key] = route_meta.render_entity(self, schema, render_content[:value], render_content[:options])
         rescue JsonSchema::ValidationErrors => e
           # 错误信息再度绑定 key
           errors.merge! e.errors.transform_keys! { |k| k.empty? ? key : "#{key}.#{k}" }
@@ -152,28 +144,6 @@ module Meta
       json
     end
 
-    def parse_request_body_for_replacing
-      request_body_schema.filter(
-        params(:raw),
-        **Meta.config.json_schema_user_options,
-        **Meta.config.json_schema_param_stage_options,
-        execution: self, stage: :param
-      )
-    rescue JsonSchema::ValidationErrors => e
-      raise Errors::ParameterInvalid.new(e.errors)
-    end
-
-    def parse_request_body_for_updating
-      request_body_schema.filter(
-        params(:raw),
-        **Meta.config.json_schema_user_options,
-        **Meta.config.json_schema_param_stage_options,
-        execution: self, stage: :param, discard_missing: true
-      )
-    rescue JsonSchema::ValidationErrors => e
-      raise Errors::ParameterInvalid.new(e.errors)
-    end
-
     class Abort < Exception
     end
 

data/lib/meta/application/metadata.rb

@@ -1,24 +1,86 @@
 # frozen_string_literal: true
+
 require_relative 'parameters'
+require_relative 'responses'
 
 module Meta
   class Metadata
-    attr_reader :title, :description, :tags, :parameters, :request_body, :responses
+    module ExecutionMethods
+      def parse_parameters(execution)
+        parameters.filter(execution.request)
+      rescue JsonSchema::ValidationErrors => e
+        raise Errors::ParameterInvalid.new(e.errors)
+      end
+
+      def parse_request_body(execution, discard_missing: false)
+        method = execution.request.request_method.downcase.to_sym
+        request_body.filter(
+          execution.params(:raw),
+          **Meta.config.json_schema_user_options,
+          **Meta.config.json_schema_param_stage_user_options,
+          **{ execution: execution, stage: :param, scope: @scope.concat(["$#{method}"]), discard_missing: discard_missing }.compact
+        )
+      rescue JsonSchema::ValidationErrors => e
+        raise Errors::ParameterInvalid.new(e.errors)
+      end
+
+      def render_entity(execution, entity_schema, value, user_options)
+        method = execution.request.request_method.downcase.to_sym
+        entity_schema.filter(value,
+          **Meta.config.json_schema_user_options,
+          **Meta.config.json_schema_render_stage_user_options,
+          **{ execution: execution, stage: :render, scope: @scope.concat([method]) }.compact,
+          **user_options,
+        )
+      end
+
+      def set_response(execution)
+        set_status(execution)
+        render_response_body(execution) if self.responses
+      end
+
+      private
+
+      def set_status(execution)
+        response_definitions = self.responses
+        response = execution.response
+        if response.status == 0
+          response.status = (response_definitions&.length > 0) ? response_definitions.keys[0] : 200
+        end
+      end
+
+      def render_response_body(execution)
+        response_definitions = self[:responses]
+        return if response_definitions.empty? # 未设定 status 宏时不需要执行 render_entity 方法
+
+        # 查找 entity schema
+        entity_schema = response_definitions[execution.response.status]
+        return if entity_schema.nil?
+
+        # 执行面向 schema 的渲染
+        execution.render_entity(entity_schema)
+      end
+    end
+
+    include ExecutionMethods
 
-    def initialize(title: nil, description: nil, tags: [], parameters: {}, request_body: nil, responses: nil)
+    attr_reader :title, :description, :tags, :parameters, :request_body, :responses, :scope
+
+    def initialize(title: nil, description: nil, tags: [], parameters: {}, request_body: nil, responses: nil, scope: nil)
       @title = title
       @description = description
       @tags = tags
       @parameters = parameters.is_a?(Parameters) ? parameters : Parameters.new(parameters)
       @request_body = request_body
-      @responses = responses || {} # || { 204 => nil }
+      @responses = responses.is_a?(Responses) ? responses : Responses.new(responses)
+      @scope = scope
     end
 
     def [](key)
       send(key)
     end
 
-    def generate_operation_doc(schemas)
+    def generate_operation_doc(schemas, scope: [])
       operation_object = {}
 
       operation_object[:summary] = title if title
@@ -28,7 +90,7 @@ module Meta
       operation_object[:parameters] = parameters.to_swagger_doc
 
       if request_body
-        schema = request_body.to_schema_doc(stage: :param, schemas: schemas)
+        schema = request_body.to_schema_doc(stage: :param, scope: self.scope + scope, schema_docs_mapping: schemas)
         if schema || true
           operation_object[:requestBody] = {
             content: {
@@ -40,16 +102,7 @@ module Meta
         end
       end
 
-      operation_object[:responses] = responses.transform_values do |schema|
-        {
-          description: '', # description 属性必须存在
-          content: schema ? {
-            'application/json' => {
-              schema: schema.to_schema_doc(stage: :render, schemas: schemas)
-            }
-          } : nil
-        }.compact
-      end unless responses.empty?
+      operation_object[:responses] = responses.to_swagger_doc(schemas, scope: self.scope + scope)
 
       operation_object.compact
     end

data/lib/meta/application/responses.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Meta
+  class Responses
+    extend Forwardable
+
+    attr_reader :responses
+
+    def initialize(responses = {})
+      @responses = responses || {}
+    end
+
+    def_delegators :@responses, :[], :empty?, :length, :keys
+
+    def to_swagger_doc(schemas, scope:)
+      if responses.empty?
+        { '200' => { description: '' } }
+      else
+        responses.transform_values do |schema|
+          {
+            description: '', # description 属性必须存在
+            content: schema ? {
+              'application/json' => {
+                schema: schema.to_schema_doc(stage: :render, scope: scope, schema_docs_mapping: schemas)
+              }
+            } : nil
+          }.compact
+        end
+      end
+    end
+  end
+end

data/lib/meta/application/route.rb

@@ -21,13 +21,9 @@ module Meta
     def execute(execution, remaining_path)
       path_matching.merge_path_params(remaining_path, execution.request)
 
-      execution.parse_parameters(@meta[:parameters]) if @meta[:parameters]
-      execution.parse_request_body(@meta[:request_body]) if @meta[:request_body]
-
+      execution.route_meta = @meta # 解析参数的准备
       action.execute(execution) if action
-
-      set_status(execution)
-      render_entity(execution) if @meta[:responses]
+      @meta.set_response(execution) if @meta.responses
     rescue Execution::Abort
       execution.response.status = 200 if execution.response.status == 0
     end
@@ -42,26 +38,8 @@ module Meta
       return true
     end
 
-    private
-
-    def set_status(execution)
-      response_definitions = @meta[:responses]
-      response = execution.response
-      if response.status == 0
-        response.status = (response_definitions&.length > 0) ? response_definitions.keys[0] : 200
-      end
-    end
-
-    def render_entity(execution)
-      response_definitions = @meta[:responses]
-      return if response_definitions.empty? # 未设定 status 宏时不需要执行 render_entity 方法
-
-      # 查找 entity schema
-      entity_schema = response_definitions[execution.response.status]
-      return if entity_schema.nil?
-
-      # 执行面向 schema 的渲染
-      execution.render_entity(entity_schema)
+    def generate_operation_doc(schemas)
+      meta.generate_operation_doc(schemas, scope: ["$#{method}"])
     end
   end
 end

data/lib/meta/config.rb

@@ -4,10 +4,9 @@ require 'hash_to_struct'
 
 module Meta
   DEFAULT_OPTIONS = {
-    default_locked_scope: nil,
     json_schema_user_options: {},
-    json_schema_param_stage_options: {},
-    json_schema_render_stage_options: {}
+    json_schema_param_stage_user_options: {},
+    json_schema_render_stage_user_options: {}
   }
 
   class << self

data/lib/meta/entity.rb

@@ -14,9 +14,7 @@ module Meta
       def inherited(base)
         base.instance_eval do
           @schema_builder = JsonSchema::ObjectSchemaBuilder.new
-          @schema_builder.schema_name(proc { |locked_scope, stage|
-            generate_schema_name(locked_scope, stage)
-          })
+          @schema_builder.schema_name(self.name) if self.name
         end
       end
 
@@ -32,6 +30,7 @@ module Meta
 
       private
 
+      # TODO: 不需要在 Entity 内自动生成名称了，交给 ObjectSchema::Naming 去做吧
       def generate_schema_name(stage, locked_scopes)
         # 匿名类不考虑自动生成名称
         return nil unless self.name

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

@@ -5,6 +5,30 @@ require_relative '../schemas/properties'
 module Meta
   module JsonSchema
     class ObjectSchemaBuilder
+      module LockedMethodAlias
+        # 我在这里说明一下 lock_scope 的逻辑。
+        # 1. lock_scope 实际上是将 scope 传递到当前的 ObjectSchema 和它的子 Schema 中。
+        # 2. lock_scope 会叠加，也就是如果子 schema 也有 lock_scope，那么子 Schema 会将两个 Schema 合并起来。
+        # 3. 调用 filter(scope:) 和 to_schema_doc(scope:) 时，可以传递 scope 参数，这个 scope 遇到 lock_scope 时会合并。
+        # 4. 这也就是说，在路由级别定义的 scope 宏会传递到下面的 Schema 中去。
+        def add_scope(scope)
+          lock_scope(scope)
+        end
+
+        def lock(key, value)
+          locked(key => value)
+        end
+
+        def method_missing(method, *args)
+          if method =~ /^lock_(\w+)$/
+            key = Regexp.last_match(1)
+            lock(key.to_sym, *args)
+          else
+            super
+          end
+        end
+      end
+
       def initialize(options = {}, &)
         raise 'type 选项必须是 object' if !options[:type].nil? && options[:type] != 'object'
 
@@ -23,23 +47,10 @@ module Meta
         instance_exec(&) if block_given?
       end
 
-      # 设置 schema_name.
-      #
-      # 一、可以传递一个块，该块会接收 locked_scope 参数，需要返回一个带有 param 和 render 键的 Hash.
-      # 二、可以传递一个 Hash，它包含 param 和 render 键。
-      # 三、可以传递一个字符串。
-      def schema_name(schema_name_resolver)
-        if schema_name_resolver.is_a?(Proc)
-          @schema_name_resolver = schema_name_resolver
-        elsif schema_name_resolver.is_a?(Hash)
-          @schema_name_resolver = proc { |stage, locked_scopes| schema_name_resolver[stage] }
-        elsif schema_name_resolver.is_a?(String)
-          @schema_name_resolver = proc { |stage, locked_scopes| schema_name_resolver }
-        elsif schema_name_resolver.nil?
-          @schema_name_resolver = proc { nil }
-        else
-          raise TypeError, "schema_name_resolver 必须是一个 Proc、Hash 或 String，当前是：#{schema_name_resolver.class}"
-        end
+      def schema_name(schema_base_name)
+        raise TypeError, "schema_base_name 必须是一个 String，当前是：#{schema_base_name.class}" unless schema_base_name.is_a?(String)
+
+        @schema_name = schema_base_name
       end
 
       def property(name, options = {}, &block)
@@ -56,16 +67,14 @@ module Meta
       end
 
       def to_schema(locked_options = nil)
-        ObjectSchema.new(properties: @properties, options: @options, locked_options: locked_options, schema_name_resolver: @schema_name_resolver)
-      end
-
-      def lock(key, value)
-        locked(key => value)
+        properties = @schema_name ? NamedProperties.new(@properties, @schema_name) : Properties.new(@properties)
+        ObjectSchema.new(properties: properties, options: @options, locked_options: locked_options)
       end
 
       def locked(options)
-        Locked.new(self, options)
+        Locked.new(self, **options)
       end
+      include LockedMethodAlias
 
       private
 
@@ -77,29 +86,25 @@ module Meta
         (options[:type] == 'object' || block) && (options[:properties] || block)
       end
 
-      def method_missing(method, *args)
-        if method =~ /^lock_(\w+)$/
-          key = Regexp.last_match(1)
-          lock(key.to_sym, *args)
-        else
-          super
-        end
-      end
-
       class Locked
-        attr_reader :builder, :locked_options
+        attr_reader :object_schema_builder, :locked_options
 
-        def initialize(builder, locked_options)
-          @builder = builder
-          @locked_options = locked_options
+        # locked_options 是用户传递的参数，这个参数会被合并到 object_schema_builder 的 locked_options 中。
+        def initialize(builder, scope: nil, discard_missing: nil, exclude: nil)
+          @object_schema_builder = builder
+          @locked_options = ObjectSchema::USER_OPTIONS_CHECKER.check({ scope: scope, discard_missing: discard_missing, exclude: exclude }.compact)
         end
 
-        # 当调用 Entity.locked 方法后，生成 schema 的方法会掉到这里面来。
-        # 在生成 schema 时，locked_options 会覆盖；当生成 schema 文档时，由于缺失 schema_name 的
-        # 信息，故而 schema_name 相关的影响就消失不见了。
         def to_schema
-          builder.to_schema(locked_options)
+          object_schema_builder.to_schema(locked_options)
+        end
+
+        def locked(options)
+          options = ObjectSchema::USER_OPTIONS_CHECKER.check(options)
+          options = ObjectSchema.merge_user_options(locked_options, options)
+          Locked.new(self.object_schema_builder, **options)
         end
+        include LockedMethodAlias
       end
     end
   end

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

@@ -4,6 +4,7 @@ require_relative 'ref_schema_builder'
 require_relative 'dynamic_schema_builder'
 require_relative 'array_schema_builder'
 require_relative 'object_schema_builder'
+require_relative '../schemas/staging_schema'
 
 module Meta
   module JsonSchema
@@ -13,11 +14,7 @@ module Meta
           permit_extras true
 
           key :ref, alias_names: [:using], normalizer: ->(entity) {
-            if Meta.config.default_locked_scope && entity.is_a?(Class) && entity < Meta::Entity
-              entity.locked(scope: Meta.config.default_locked_scope)
-            else
-              entity
-            end
+            entity
           }
           key :dynamic_ref, alias_names: [:dynamic_using], normalizer: ->(value) { value.is_a?(Proc) ? { resolve: value } : value }
         end

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

@@ -3,6 +3,8 @@
 module Meta
   module JsonSchema
     class ArraySchema < BaseSchema
+      extend Forwardable
+
       attr_reader :items
 
       def initialize(items, options = {})
@@ -11,20 +13,6 @@ module Meta
         @items = items
       end
 
-      def filter(array_value, options = {})
-        array_value = super(array_value, options)
-        return nil if array_value.nil?
-        raise ValidationError.new('参数应该传递一个数组') unless array_value.respond_to?(:each_with_index)
-
-        array_value.each_with_index.map do |item, index|
-          begin
-            @items.filter(item, **options)
-          rescue ValidationErrors => e
-            raise e.prepend_root("[#{index}]")
-          end
-        end
-      end
-
       def to_schema_doc(**user_options)
         stage_options = options
 
@@ -35,6 +23,28 @@ module Meta
         schema[:description] = stage_options[:description] if stage_options[:description]
         schema
       end
+
+      def_delegator :@items, :defined_scopes
+
+      private
+
+      def filter_internal(array_value, user_options)
+        if array_value.respond_to?(:each_with_index)
+          array_value = array_value
+        elsif array_value.respond_to?(:to_a)
+          array_value = array_value.to_a
+        else
+          raise ValidationError.new('参数应该传递一个数组或者数组 Like 的对象（实现了 each_with_index 或者 to_a 方法）')
+        end
+
+        array_value.each_with_index.map do |item, index|
+          begin
+            @items.filter(item, user_options)
+          rescue ValidationErrors => e
+            raise e.prepend_root("[#{index}]")
+          end
+        end
+      end
     end
   end
 end