meta-api 0.0.2 → 0.0.3

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

@@ -1,18 +1,28 @@
 # frozen_string_literal: true
 
-require_relative '../../utils/kwargs'
+require_relative '../../utils/kwargs/check'
 
 module Meta
   module JsonSchema
     class ObjectSchema < BaseSchema
-      attr_reader :properties, :object_validations, :locked_options
+      attr_reader :properties, :locked_options
 
-      def initialize(properties: {}, object_validations: {}, options: {}, locked_options: {}, schema_name_resolver: proc { nil })
+      USER_OPTIONS_CHECKER = Utils::KeywordArgs::Builder.build do
+        permit_extras true
+
+        key :scope, normalizer: ->(value) {
+          raise ArgumentError, 'scope 选项不可传递 nil' if value.nil?
+          value = [value] unless value.is_a?(Array)
+          value
+        }
+      end
+
+      def initialize(properties: nil, options: {}, locked_options: {}, schema_name_resolver: proc { nil })
         super(options)
 
-        @properties = properties || {}
-        @object_validations = object_validations || {}
-        @locked_options = locked_options || {}
+        @properties = properties || Properties.new({}) # property 包含 stage，stage 包含 scope、schema
+        @properties = Properties.new(@properties) if @properties.is_a?(Hash)
+        @locked_options = USER_OPTIONS_CHECKER.check(locked_options || {})
         @schema_name_resolver = schema_name_resolver || proc { nil }
       end
 
@@ -20,7 +30,6 @@ module Meta
       def dup(options)
         self.class.new(
           properties: properties,
-          object_validations: object_validations,
           options: options,
           locked_options: locked_options,
           schema_name_resolver: @schema_name_resolver
@@ -30,52 +39,12 @@ module Meta
       def filter(object_value, user_options = {})
         # 合并 user_options
         user_options = user_options.merge(locked_options) if locked_options
+        user_options = USER_OPTIONS_CHECKER.check(user_options)
 
         object_value = super(object_value, user_options)
-        return nil if object_value.nil?
 
-        # 第一步，根据 user_options[:scope] 需要过滤一些字段
-        # user_options[:scope] 应是一个数组
-        user_scope = user_options[:scope] || []
-        user_scope = [user_scope] unless user_scope.is_a?(Array)
-        stage = user_options[:stage]
-        exclude = user_options.delete(:exclude) # 这里删除 exclude 选项
-        filtered_properties = @properties.filter do |name, property_schema|
-          # 通过 discard_missing 过滤
-          next false if user_options[:discard_missing] && !object_value.key?(name.to_s)
-
-          # 通过 stage 过滤。
-          property_schema_options = property_schema.options(stage)
-          next false unless property_schema_options
-
-          # 通过 locked_exclude 选项过滤
-          next false if exclude && exclude.include?(name)
-
-          # 通过 scope 过滤
-          scope_option = property_schema_options[:scope]
-          next true if scope_option.empty?
-          next false if user_scope.empty?
-          (user_scope - scope_option).empty? # user_scope 应被消耗殆尽
-        end
-
-        # 第二步，递归过滤每一个属性
-        object = {}
-        errors = {}
-        filtered_properties.each do |name, property_schema|
-          value = resolve_property_value(object_value, name, property_schema, stage)
-
-          begin
-            object[name] = property_schema.filter(value, **user_options, object_value: object_value)
-          rescue JsonSchema::ValidationErrors => e
-            errors.merge! e.prepend_root(name).errors
-          end
-        end.to_h
-
-        if errors.empty?
-          object
-        else
-          raise JsonSchema::ValidationErrors.new(errors)
-        end
+        return nil if object_value.nil?
+        @properties.filter(object_value, user_options)
       end
 
       # 合并其他的属性，并返回一个新的 ObjectSchema
@@ -83,61 +52,18 @@ module Meta
         ObjectSchema.new(properties: self.properties.merge(properties))
       end
 
-      # 生成 Swagger 文档的 schema 格式。
-      #
-      # 选项：
-      # - stage: 传递 :param 或 :render
-      # - schemas: 用于保存已经生成的 Schema
-      # - to_ref: 是否生成 $ref 格式，默认为“是”
-      #
-      # 提示：
-      # > 每个 ObjectSchema 拥有一个 @schema_name_resolver 实例变量，如果由它解析出来的名称不为 nil，
-      # > 则该 Schema 生成文档时会使用 $ref 格式。除非 to_ref 选项设置为 false.
-      #
-      def to_schema_doc(user_options)
-        Utils::KeywordArgs.check(
-          args: user_options,
-          schema: { stage: nil, scope: nil, to_ref: false, schemas: nil }
-        )
+      def resolve_name(stage)
+        locked_scopes = (locked_options || {})[:scope] || []
+        @schema_name_resolver.call(stage, locked_scopes)
+      end
 
-        stage = user_options[:stage]
+      def to_schema_doc(stage: nil, **user_options)
         locked_scopes = (locked_options || {})[:scope] || []
-        locked_scopes = [locked_scopes] unless locked_scope.nil? && locked_scopes.is_a?(Array)
-        schema_name = @schema_name_resolver.call(stage, locked_scopes)
-        if schema_name && user_options[:to_ref] != false
-          # 首先将 Schema 写进 schemas 选项中去
-          schemas = user_options[:schemas]
-          unless schemas.key?(schema_name)
-            schemas[schema_name] = nil # 首先设置 schemas 防止出现无限循环
-            schemas[schema_name] = to_schema_doc(**user_options, to_ref: false) # 原地修改 schemas，无妨
-          end
-
-          return { '$ref': "#/components/schemas/#{schema_name}" }
-        end
-
-        stage_options = options(stage)
-        properties = @properties.filter do |name, property_schema|
-          # 根据 stage 过滤
-          next false if stage.nil?
-          next false if stage == :param && !property_schema.options(:param)
-          next false if stage == :render && !property_schema.options(:render)
-
-          # 根据 locked_scope 过滤
-          next true if locked_scopes.empty? # locked_scope 未提供时不过滤
-          property_scope = property_schema.options(stage, :scope)
-          property_scope = [property_scope] unless property_scope.is_a?(Array)
-          next true if property_scope.empty?
-          (locked_scopes - property_scope).empty? # user_scope 应被消耗殆尽
-        end
-        required_keys = properties.filter do |key, property_schema|
-          property_schema.options(stage, :required)
-        end.keys
-        properties = properties.transform_values do |property_schema|
-          property_schema.to_schema_doc(**user_options, to_ref: true)
-        end
 
         schema = { type: 'object' }
-        schema[:description] = stage_options[:description] if stage_options[:description]
+        schema[:description] = options[:description] if options[:description]
+
+        properties, required_keys = @properties.to_swagger_doc(stage: stage, locked_scopes: locked_scopes, **user_options)
         schema[:properties] = properties unless properties.empty?
         schema[:required] = required_keys unless required_keys.empty?
         schema
@@ -150,18 +76,6 @@ module Meta
       def locked_exclude
         locked_options && locked_options[:exclude]
       end
-
-      private
-
-        def resolve_property_value(object_value, name, property_schema, stage)
-          if property_schema.value?(stage)
-            nil
-          elsif object_value.is_a?(Hash) || object_value.is_a?(ObjectWrapper)
-            object_value.key?(name.to_s) ? object_value[name.to_s] : object_value[name.to_sym]
-          else
-            raise "不应该还有其他类型了，已经在类型转换中将其转换为 Meta::JsonSchema::ObjectWrapper 了"
-          end
-        end
     end
   end
 end

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

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+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)
+        @properties = properties
+      end
+
+      def filter(object_value, user_options = {})
+        # 第一步，根据 user_options[:scope] 需要过滤一些字段
+        stage = user_options[:stage]
+        # 传递一个数字；因为 scope 不能包含数字，这里传递一个数字，使得凡是配置 scope 的属性都会被过滤
+        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|
+          # 通过 discard_missing 过滤
+          next false if user_options[:discard_missing] && !object_value.key?(name.to_s)
+
+          # 通过 locked_exclude 选项过滤
+          next false if exclude && exclude.include?(name)
+
+          # 默认返回 true
+          next true
+        end
+
+        # 第二步，递归过滤每一个属性
+        object = {}
+        errors = {}
+        filtered_properties.each do |name, property_schema|
+          value = resolve_property_value(object_value, name, property_schema, stage)
+
+          begin
+            object[name] = property_schema.filter(value, **user_options, object_value: object_value)
+          rescue JsonSchema::ValidationErrors => e
+            errors.merge! e.prepend_root(name).errors
+          end
+        end.to_h
+
+        if errors.empty?
+          object
+        else
+          raise JsonSchema::ValidationErrors.new(errors)
+        end
+      end
+
+      def to_swagger_doc(locked_scopes:, stage:, **user_options)
+        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)
+        end
+        [properties, required_keys]
+      end
+
+      # 程序中有些地方用到了这三个方法
+      def_delegators :@properties, :empty?, :key?, :[]
+
+      def self.build_property(*args)
+        StagingProperty.build(*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
+        end
+      end
+
+      def resolve_property_value(object_value, name, property_schema, stage)
+        if property_schema.value?
+          nil
+        elsif object_value.is_a?(Hash) || object_value.is_a?(ObjectWrapper)
+          object_value.key?(name.to_s) ? object_value[name.to_s] : object_value[name.to_sym]
+        else
+          raise "不应该还有其他类型了，已经在类型转换中将其转换为 Meta::JsonSchema::ObjectWrapper 了"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative 'base_schema'
+
+module Meta
+  module JsonSchema
+    class RefSchema < BaseSchema
+      attr_reader :schema
+
+      def initialize(schema, options = {})
+        super(options)
+        @schema = schema
+      end
+
+      def filter(value, user_options = {})
+        value = super
+        schema.filter(value, user_options)
+      end
+
+      def to_schema_doc(user_options)
+        schema_name = schema.resolve_name(user_options[:stage])
+
+        # 首先将 Schema 写进 schemas 选项中去
+        schema_components = user_options[:schemas]
+        unless schema_components.key?(schema_name)
+          schema_components[schema_name] = nil # 首先设置 schemas 防止出现无限循环
+          schema_components[schema_name] = schema.to_schema_doc(**user_options) # 原地修改 schemas，无妨
+        end
+
+        # 返回的是 $ref 结构
+        { '$ref': "#/components/schemas/#{schema_name}" }
+      end
+    end
+  end
+end

data/lib/meta/json_schema/schemas.rb

@@ -7,6 +7,4 @@ require_relative 'support/presenters'
 require_relative 'schemas/base_schema'
 require_relative 'schemas/object_schema'
 require_relative 'schemas/array_schema'
-require_relative 'builders/object_schema_builder'
-require_relative 'builders/array_schema_builder'
 require_relative 'builders/schema_builder_tool'

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

@@ -1,8 +1,17 @@
 # frozen_string_literal: true
 
+require_relative '../../utils/kwargs/builder'
+
 module Meta
   module JsonSchema
     module SchemaOptions
+      OPTIONS_CHECKER = Utils::KeywordArgs::Builder.build do
+        key :type, :items, :description, :presenter, :value, :format, :required, :default, :validate, :allowable, :properties, :convert
+        key :using, normalizer: ->(value) { value.is_a?(Proc) ? { resolve: value } : value }
+        key :param
+        key :render
+      end
+
       @default_options = {
         scope: [],
         required: false
@@ -14,29 +23,21 @@ module Meta
       ).uniq
 
       class << self
-        def normalize_to_param_and_render(options)
+        def divide_to_param_and_render(options)
           common_opts = (options || {}).dup
           param_opts = common_opts.delete(:param)
           render_opts = common_opts.delete(:render)
 
           param_opts = merge_common_to_stage(common_opts, param_opts)
           render_opts = merge_common_to_stage(common_opts, render_opts)
-          [param_opts, render_opts]
-        end
-
-        def merge_common_to_stage(common_opts, stage_opts)
-          stage_opts = {} if stage_opts.nil? || stage_opts == true
-          stage_opts = common_opts.merge(stage_opts) if stage_opts
-          stage_opts = normalize(stage_opts) if stage_opts
-          stage_opts
+          [param_opts, render_opts, common_opts]
         end
 
         def normalize(options)
+          options = OPTIONS_CHECKER.check(options)
+
           # 只要 options 中设置为 nil 的选项没有明确的意义，则下行代码是永远有效的
           options = (@default_options.compact).merge(options.compact)
-          options[:scope] = [options[:scope]] unless options[:scope].is_a?(Array)
-          # TODO: 更好的规范选项的方式，以及如何检查深层次嵌套下参数类型的错误
-          options[:using] = { resolve: options[:using] } if options[:using].is_a?(Proc)
           if options[:using]
             if options[:type].nil?
               options[:type] = 'object'
@@ -51,6 +52,14 @@ module Meta
 
           options
         end
+
+        private
+
+        def merge_common_to_stage(common_opts, stage_opts)
+          stage_opts = {} if stage_opts.nil? || stage_opts == true
+          stage_opts = common_opts.merge(stage_opts) if stage_opts
+          stage_opts
+        end
       end
     end
   end

data/lib/meta/json_schema.rb

@@ -0,0 +1,2 @@
+require_relative 'load_i18n'
+require_relative 'json_schema/schemas'

data/lib/meta/rails.rb

@@ -0,0 +1,98 @@
+# 作为 Rails 插件
+
+require_relative 'errors'
+require_relative 'json_schema/schemas'
+
+module Meta
+  module Rails
+    def self.setup
+      # 第一步，为 ActionController 添加一个新的 Renderer
+      ActionController::Renderers.add :json_on_schema do |obj, options|
+        options = options.dup
+        status = options.delete(:status) || 200
+        scope = options.delete(:scope) || :all
+
+        route_definitions = self.class.route_definitions
+        route_definition = route_definitions[[self.class, params[:action].to_sym]]
+        raise '未绑定 Route 定义' unless route_definition
+
+        meta_definition = route_definition.meta
+        raise '未提供 status 宏定义' unless meta_definition[:responses] && meta_definition[:responses][status]
+
+        render_schema = meta_definition[:responses][status]
+        str = render_schema.filter(obj, execution: self, stage: :render, scope: scope)
+        render json: str, **options
+      rescue JsonSchema::ValidationErrors => e
+        raise Errors::RenderingInvalid.new(e.errors)
+      end
+    end
+
+    module Plugin
+      def self.generate_swagger_doc(klass, **kwargs)
+        paths_and_routes = klass.route_definitions.values.map do |route_definition|
+          [route_definition.path, route_definition]
+        end
+        SwaggerDocUtil.generate_from_paths_and_routes(paths_and_routes, **kwargs)
+      end
+
+      def self.included(base)
+        # 已经被父类引入过，不再重复引入
+        return if self.respond_to?(:route_definitions)
+
+        # 为 ActionController 引入宏命令，宏命令在子类中生效
+        base.extend ClassMethods
+
+        # 为 ActionController 定义一个 Route Definitions，子类实例可以通过 self.class.route_definitions 访问
+        route_definitions = {}
+        base.define_singleton_method(:route_definitions) { route_definitions }
+
+        # 定义一个方法，子类在定义方法后，将当前的路由定义应用到该方法上
+        base.define_singleton_method(:apply_route_definition) do |klass, method_name|
+          if @current_route_builder
+            self.route_definitions[[klass, method_name]] = @current_route_builder.build
+            @current_route_builder = nil
+          end
+        end
+        # 触发 apply_route_definition 方法
+        base.define_singleton_method(:method_added) do |name|
+          apply_route_definition(self, name)
+        end
+
+        # 为 ActionController 定义一个方法，用于获取过滤后的参数
+        attr_accessor :params_on_schema
+
+        # 为 ActionController 定义一个 before_action，用于过滤参数
+        base.before_action do
+          route_definitions = self.class.route_definitions
+          route_definition = route_definitions[[self.class, params[:action].to_sym]]
+          next unless route_definition
+
+          meta_definition = route_definition.meta
+          next if meta_definition[:parameters].empty? && meta_definition[:request_body].nil?
+
+          raw_params = self.params.to_unsafe_h
+          final_params = {}
+
+          if meta_definition[:parameters]
+            parameters_meta = meta_definition[:parameters]
+            final_params = parameters_meta.filter(request)
+          end
+          if meta_definition[:request_body]
+            params_schema = meta_definition[:request_body]
+            final_params.merge! params_schema.filter(raw_params, stage: :param)
+          end
+
+          self.params_on_schema = final_params
+        rescue JsonSchema::ValidationErrors => e
+          raise Errors::ParameterInvalid.new(e.errors)
+        end
+      end
+
+      module ClassMethods
+        def route(path = '', method = :all, &block)
+          @current_route_builder = RouteDSL::RouteBuilder.new(path, method, &block)
+        end
+      end
+    end
+  end
+end

data/lib/meta/route_dsl/parameters_builder.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+require_relative '../application/parameters'
 
 module Meta
   module RouteDSL
@@ -17,7 +18,7 @@ module Meta
       end
 
       def build
-        @parameters
+        Parameters.new(@parameters)
       end
     end
   end

data/lib/meta/swagger_doc.rb

@@ -4,10 +4,13 @@ module Meta
   module SwaggerDocUtil
     class << self
       def generate(application, info: {}, servers: [])
-        routes = get_paths_and_routes!(application)
+        paths_and_routes = get_paths_and_routes!(application)
+        return generate_from_paths_and_routes(paths_and_routes, info: info, servers: servers)
+      end
 
+      def generate_from_paths_and_routes(paths_and_routes, info: {}, servers: [])
         schemas = {}
-        paths = routes.group_by { |path, route| path }.map { |path, routes| [path, routes.map { |item| item[1] }]}.map do |path, routes|
+        paths = paths_and_routes.group_by { |path, route| path }.map { |path, routes| [path, routes.map { |item| item[1] }]}.map do |path, routes|
           operations = routes.map do |route|
             [route.method.downcase.to_sym, generate_operation_object(route, schemas)]
           end.to_h