meta-api 0.0.8 → 0.1.0

data/docs//347/264/242/345/274/225.md

@@ -1,183 +0,0 @@
-# 索引
-
-## 属性校验
-
-### `validate`
-
-通用的校验器，可传递一个自定义的块。注意，如果校验不通过，需要主动地抛出 `Meta::JsonSchema::ValidationError`. 例如：
-
-```ruby
-property :mobile, validate: lambda do |value|
-  raise Meta::JsonSchema::ValidationError, '手机号格式不正确' unless value =~ /\d+/
-end
-```
-
-### `required`
-
-有关必须要传递的字段可通过 `required: true` 设置。
-
-```ruby
-property :name, required: true # 必须
-property :age, required: false # 非必须
-```
-
-对于字符串属性，即使是空白字符串也无法通过 `required` 校验。这时可通过设置 `allow_empty: true` 来改变这一行为。
-
-```ruby
-property :name, required: { allow_empty: true }
-```
-
-数组属性默认是允许空数组的。如果你不喜欢这种行为，需明确设置 `allow_empty` 为 `false`.
-
-### `format`
-
-`format` 校验可传递一个正则表达式选项，参数需匹配正则表达式代表的模式。
-
-```ruby
-property :date, format: /^\d{4}-\d{2}-\d{2}$/
-```
-
-### `allowable`
-
-对于枚举值来说，通过 `allowable` 来定义可选项。
-
-```ruby
-property :gender, allowable: ['male', 'female']
-```
-
-如果用户传递了不同于 `male` 或 `female` 的值，就会报错。
-
-## 错误列表
-
-框架中使用 `rescue_error` 捕获异常，框架能够抛出的异常包括：
-
-- `Meta::Errors::NoMatchingRoute`：路由不匹配时。
-- `Meta::Errors::ParameterInvalid`：参数存在异常时。
-- `Meta::Errors::RenderingInvalid`：响应值存在异常时。
-- `Meta::Errors::UnsupportedContentType`：框架只支持 `application/json` 的参数格式。当客户端的请求体不是这个格式时，会抛出这个错误。
-
-## I18n
-
-框架默认提供的语言是 `zh-CN`，可通过文件 `config/locales/zh-CN.yml` 查看可配置的内容。如果需要添加其他语言的支持，需要自行配置。
-
-## `lock` 系列方法
-
-`locked` 方法返回一个新的实体，它将若干选项锁定。例如，锁定某个实体为 `scope: 'full'`：
-
-```ruby
-# 如下定义一个 Entity
-class ArticleEntity < Meta::Entity
-  property :title, type: 'string'
-  property :content, type: 'string', scope: 'full'
-  property :hidden, type: 'boolean', scope: 'o'
-end
-
-# 在 using 时锁定 scope
-params do
-  property :article, using: ArticleEntity.locked(scope: 'full')
-end
-```
-
-如上，`article` 内容仅包含字段 `title`、`content`.
-
-再例如，我们也可以去掉某些指定的字段，这时用到 `exclude: ...` 选项。下面的例子将达到与上面例子等效的结果：
-
-```ruby
-# 在 using 时去掉某些字段
-params do
-  property :article, using: ArticleEntity.locked(exclude: [:hidden])
-end
-```
-
-注意 `exclude` 的传递格式，它接受一个数组，并且字段应用符号而不是字符串。
-
-最后一个示例是如何处理缺失字段的。在处理请求参数时，我们有时候需要包括缺失字段，有时候需要去掉缺失字段。默认情况下是按照前者处理的，如果需要按照后者的方式处理，需要锁定选项 `discard_missing: true`：
-
-```ruby
-# 在 using 时不包括缺失字段
-params do
-  property :article, using: ArticleEntity.locked(discard_missing: true)
-end
-```
-
-我们也可以综合这几个选项（由于综合 `scope` 和 `exclude` 往往没有意义，这里我们只综合 `scope` 和 `discard_missing`）：
-
-```ruby
-params do
-  property :article, using: ArticleEntity.locked(scope: ['full'], discard_missing: true)
-end
-```
-
-如上，`scope` 选项也可以传递数组的。
-
-除了 `locked` 方法，还包括几个便捷方法。例如 `lock` 方法，它与 `locked` 在某种程度上等价：
-
-```ruby
-ArticleEntity.lock(:scope, 'full')         # 它与 locked(scope: 'full') 等价
-ArticleEntity.lock(:discard_missing, true) # 它与 locked(discard_missing: true) 等价
-```
-
-还有 `lock_xxx` 便捷方法：
-
-```ruby
-ArticleEntity.lock_scope('full')           # 它与 locked(scope: 'full') 等价
-```
-
-## `parameters` 、`request_body` 和 Open API 规格定义
-
-在 Open API 中，参数和请求体是分开定义的，它们不属于同一个语义。下面是一个 HTTP 请求的示例：
-
-```http
-POST /request?foo=foo
-X-Bar: bar
-
-{
-  "user": ...
-}
-```
-
-其中 `foo=foo` 和 `X-Bar: bar` 是参数，而 JSON 格式的 `{ "user": ... }` 才是请求体。
-
-在 Meta 框架中，为了方便，可以用同一个宏命令（即 `params`）来定义参数和请求体：
-
-```ruby
-params do
-  param :foo, in: 'query'
-  param 'X-Bar', in: 'header'
-  param :user, type: 'object'
-end
-```
-
-而事实上，Meta 框架也给出了分开定义参数和请求体的的宏命令。也许有些混淆，`parameters` 宏专用于定义参数，`request_body` 宏用于定义请求体：
-
-```ruby
-parameters do
-  param :foo, in: 'query'
-  param 'X-Bar', in: 'header'
-end
-request_body do
-  property :user, type: 'object'
-end
-```
-
-而在应用中，也许有些混淆，`params`、`parameters`、`request_body` 能够获取到参数和请求体：
-
-```ruby
-action do
-  params       # 合并获取参数和请求体
-  parameters   # 专用于获取参数
-  request_body # 专用于获取请求体
-end
-```
-
-面对这两种使用方式，有何使用上的建议呢？我的建议是，你习惯用哪种就用哪种。
-
-## `JsonSchema#filter` 方法的用户选项
-
-### `discard_missing:`
-
-规定是否忽略缺失的属性。所谓缺失的属性，是指在 `ObjectSchema` 实体宏中定义，但数据中不包含这个键值的属性。你可以将 `discard_missing: true` 视为 HTTP Patch 方法，`discard_missing: false` 视为 HTTP Put 方法。
-
-### `extra_properties:`
-
-规定多余的属性的处理办法。所谓多余的属性，是指未在 `ObjectSchema`  实体宏中定义，但数据中依然存在这个键值的属性。一般来讲我们允许前端传递一些多余的属性，但可能在内部测试时设定为更严格的条件。

data/examples/lobster.rb

@@ -1,71 +0,0 @@
-# frozen_string_literal: true
-
-# 一个示例 Rack 应用，运行方式：`ruby -Ilib <this-file>`
-
-require 'zlib'
-
-# Paste has a Pony, Rack has a Lobster!
-class Lobster
-  LobsterString = Zlib::Inflate.inflate("eJx9kEEOwyAMBO99xd7MAcytUhPlJyj2
-    P6jy9i4k9EQyGAnBarEXeCBqSkntNXsi/ZCvC48zGQoZKikGrFMZvgS5ZHd+aGWVuWwhVF0
-    t1drVmiR42HcWNz5w3QanT+2gIvTVCiE1lm1Y0eU4JGmIIbaKwextKn8rvW+p5PIwFl8ZWJ
-    I8jyiTlhTcYXkekJAzTyYN6E08A+dk8voBkAVTJQ==".delete("\n ").unpack("m*")[0])
-
-  LambdaLobster = lambda { |env|
-    if env[Rack::QUERY_STRING].include?("flip")
-      lobster = LobsterString.split("\n").
-        map { |line| line.ljust(42).reverse }.
-        join("\n")
-      href = "?"
-    else
-      lobster = LobsterString
-      href = "?flip"
-    end
-
-    content = ["<title>Lobstericious!</title>",
-               "<pre>", lobster, "</pre>",
-               "<a href='#{href}'>flip!</a>"]
-    length = content.inject(0) { |a, e| a + e.size }.to_s
-    [200, { Rack::CONTENT_TYPE => "text/html", Rack::CONTENT_LENGTH => length }, content]
-  }
-
-  def call(env)
-    req = Rack::Request.new(env)
-    if req.GET["flip"] == "left"
-      lobster = LobsterString.split("\n").map do |line|
-        line.ljust(42).reverse.
-          gsub('\\', 'TEMP').
-          gsub('/', '\\').
-          gsub('TEMP', '/').
-          gsub('{', '}').
-          gsub('(', ')')
-      end.join("\n")
-      href = "?flip=right"
-    elsif req.GET["flip"] == "crash"
-      raise "Lobster crashed"
-    else
-      lobster = LobsterString
-      href = "?flip=left"
-    end
-
-    res = Rack::Response.new
-    res.write "<title>Lobstericious!</title>"
-    res.write "<pre>"
-    res.write lobster
-    res.write "</pre>"
-    res.write "<p><a href='#{href}'>flip!</a></p>"
-    res.write "<p><a href='?flip=crash'>crash!</a></p>"
-    res.finish
-  end
-end
-
-if $0 == __FILE__
-  # :nocov:
-  require 'rack'
-
-  app = Lobster.new # or Lobster::LambdaLobster
-  Rack::Server.start(
-    app: Rack::ShowExceptions.new(Rack::Lint.new(app)), Port: 9292
-  )
-  # :nocov:
-end

data/examples/rack_app/README.md

@@ -1,3 +0,0 @@
-# Demo Rack Application
-
-一个示例 Rack 应用，可以看到中间件的用法以及它们如何交互。

data/examples/rack_app/config.ru

@@ -1,6 +0,0 @@
-require 'rack'
-require './hello.rb'
-require './timing.rb'
-
-use Timing
-run Hello

data/examples/rack_app/hello.rb

@@ -1,6 +0,0 @@
-class Hello
-  def self.call(env)
-    puts "Timing Start: #{env['Timing-Start']}"
-    ['200', {'Content-Type' => 'text/html'}, ['Hello, Rack!']]
-  end
-end

data/examples/rack_app/timing.rb

@@ -1,15 +0,0 @@
-class Timing
-  def initialize(app)
-    @app = app
-  end
-
-  def call(env)
-    env['Timing-Start'] = Time.now.to_i
-
-    ts = Time.now
-    status, headers, body = @app.call(env)
-    elapsed_time = Time.now - ts
-    puts "Timing: #{env['REQUEST_METHOD']} #{env['REQUEST_URI']} #{elapsed_time.round(3)}"
-    return [status, headers, body]
-  end
-end

data/examples/rails_app/.gitattributes

@@ -1,5 +0,0 @@
-# See https://git-scm.com/docs/gitattributes for more about git attribute files.
-
-
-# Mark any vendored files as having been vendored.
-vendor/* linguist-vendored

data/examples/rails_app/.gitignore

@@ -1,23 +0,0 @@
-# See https://help.github.com/articles/ignoring-files for more about ignoring files.
-#
-# If you find yourself ignoring temporary files generated by your text editor
-# or operating system, you probably want to add a global ignore instead:
-#   git config --global core.excludesfile '~/.gitignore_global'
-
-# Ignore bundler config.
-/.bundle
-
-# Ignore all logfiles and tempfiles.
-/log/*
-/tmp/*
-!/log/.keep
-!/tmp/.keep
-
-# Ignore pidfiles, but keep the directory.
-/tmp/pids/*
-!/tmp/pids/
-!/tmp/pids/.keep
-
-
-# Ignore master key for decrypting credentials and more.
-/config/master.key

data/examples/rails_app/.rspec

@@ -1 +0,0 @@
---require spec_helper

data/examples/rails_app/.ruby-version

@@ -1 +0,0 @@
-3.1.2

data/examples/rails_app/Gemfile

@@ -1,29 +0,0 @@
-source "https://gems.ruby-china.com"
-git_source(:github) { |repo| "https://github.com/#{repo}.git" }
-
-ruby "3.1.2"
-
-# Bundle edge Rails instead: gem "rails", github: "rails/rails", branch: "main"
-gem "rails", "~> 7.0.4"
-gem "meta-api", path: "../.."
-
-# Use the Puma web server [https://github.com/puma/puma]
-gem "puma", "~> 5.0"
-
-# Windows does not include zoneinfo files, so bundle the tzinfo-data gem
-gem "tzinfo-data", platforms: %i[ mingw mswin x64_mingw jruby ]
-
-# Use Rack CORS for handling Cross-Origin Resource Sharing (CORS), making cross-origin AJAX possible
-# gem "rack-cors"
-
-group :development, :test do
-  # See https://guides.rubyonrails.org/debugging_rails_applications.html#debugging-with-the-debug-gem
-  gem "debug", platforms: %i[ mri mingw x64_mingw ]
-  gem 'rspec-rails', '~> 6.0.0'
-end
-
-group :development do
-  # Speed up commands on slow machines / big apps [https://github.com/rails/spring]
-  # gem "spring"
-end
-

data/examples/rails_app/Gemfile.lock

@@ -1,190 +0,0 @@
-PATH
-  remote: /home/run/workspace/personal/web-frame
-  specs:
-    meta-api (0.0.6)
-
-GEM
-  remote: https://gems.ruby-china.com/
-  specs:
-    actioncable (7.0.4.3)
-      actionpack (= 7.0.4.3)
-      activesupport (= 7.0.4.3)
-      nio4r (~> 2.0)
-      websocket-driver (>= 0.6.1)
-    actionmailbox (7.0.4.3)
-      actionpack (= 7.0.4.3)
-      activejob (= 7.0.4.3)
-      activerecord (= 7.0.4.3)
-      activestorage (= 7.0.4.3)
-      activesupport (= 7.0.4.3)
-      mail (>= 2.7.1)
-      net-imap
-      net-pop
-      net-smtp
-    actionmailer (7.0.4.3)
-      actionpack (= 7.0.4.3)
-      actionview (= 7.0.4.3)
-      activejob (= 7.0.4.3)
-      activesupport (= 7.0.4.3)
-      mail (~> 2.5, >= 2.5.4)
-      net-imap
-      net-pop
-      net-smtp
-      rails-dom-testing (~> 2.0)
-    actionpack (7.0.4.3)
-      actionview (= 7.0.4.3)
-      activesupport (= 7.0.4.3)
-      rack (~> 2.0, >= 2.2.0)
-      rack-test (>= 0.6.3)
-      rails-dom-testing (~> 2.0)
-      rails-html-sanitizer (~> 1.0, >= 1.2.0)
-    actiontext (7.0.4.3)
-      actionpack (= 7.0.4.3)
-      activerecord (= 7.0.4.3)
-      activestorage (= 7.0.4.3)
-      activesupport (= 7.0.4.3)
-      globalid (>= 0.6.0)
-      nokogiri (>= 1.8.5)
-    actionview (7.0.4.3)
-      activesupport (= 7.0.4.3)
-      builder (~> 3.1)
-      erubi (~> 1.4)
-      rails-dom-testing (~> 2.0)
-      rails-html-sanitizer (~> 1.1, >= 1.2.0)
-    activejob (7.0.4.3)
-      activesupport (= 7.0.4.3)
-      globalid (>= 0.3.6)
-    activemodel (7.0.4.3)
-      activesupport (= 7.0.4.3)
-    activerecord (7.0.4.3)
-      activemodel (= 7.0.4.3)
-      activesupport (= 7.0.4.3)
-    activestorage (7.0.4.3)
-      actionpack (= 7.0.4.3)
-      activejob (= 7.0.4.3)
-      activerecord (= 7.0.4.3)
-      activesupport (= 7.0.4.3)
-      marcel (~> 1.0)
-      mini_mime (>= 1.1.0)
-    activesupport (7.0.4.3)
-      concurrent-ruby (~> 1.0, >= 1.0.2)
-      i18n (>= 1.6, < 2)
-      minitest (>= 5.1)
-      tzinfo (~> 2.0)
-    builder (3.2.4)
-    concurrent-ruby (1.2.2)
-    crass (1.0.6)
-    date (3.3.3)
-    debug (1.7.1)
-      irb (>= 1.5.0)
-      reline (>= 0.3.1)
-    diff-lcs (1.5.0)
-    erubi (1.12.0)
-    globalid (1.1.0)
-      activesupport (>= 5.0)
-    i18n (1.12.0)
-      concurrent-ruby (~> 1.0)
-    io-console (0.6.0)
-    irb (1.6.3)
-      reline (>= 0.3.0)
-    loofah (2.19.1)
-      crass (~> 1.0.2)
-      nokogiri (>= 1.5.9)
-    mail (2.8.1)
-      mini_mime (>= 0.1.1)
-      net-imap
-      net-pop
-      net-smtp
-    marcel (1.0.2)
-    method_source (1.0.0)
-    mini_mime (1.1.2)
-    minitest (5.18.0)
-    net-imap (0.3.4)
-      date
-      net-protocol
-    net-pop (0.1.2)
-      net-protocol
-    net-protocol (0.2.1)
-      timeout
-    net-smtp (0.3.3)
-      net-protocol
-    nio4r (2.5.8)
-    nokogiri (1.14.2-x86_64-linux)
-      racc (~> 1.4)
-    puma (5.6.5)
-      nio4r (~> 2.0)
-    racc (1.6.2)
-    rack (2.2.6.4)
-    rack-test (2.1.0)
-      rack (>= 1.3)
-    rails (7.0.4.3)
-      actioncable (= 7.0.4.3)
-      actionmailbox (= 7.0.4.3)
-      actionmailer (= 7.0.4.3)
-      actionpack (= 7.0.4.3)
-      actiontext (= 7.0.4.3)
-      actionview (= 7.0.4.3)
-      activejob (= 7.0.4.3)
-      activemodel (= 7.0.4.3)
-      activerecord (= 7.0.4.3)
-      activestorage (= 7.0.4.3)
-      activesupport (= 7.0.4.3)
-      bundler (>= 1.15.0)
-      railties (= 7.0.4.3)
-    rails-dom-testing (2.0.3)
-      activesupport (>= 4.2.0)
-      nokogiri (>= 1.6)
-    rails-html-sanitizer (1.5.0)
-      loofah (~> 2.19, >= 2.19.1)
-    railties (7.0.4.3)
-      actionpack (= 7.0.4.3)
-      activesupport (= 7.0.4.3)
-      method_source
-      rake (>= 12.2)
-      thor (~> 1.0)
-      zeitwerk (~> 2.5)
-    rake (13.0.6)
-    reline (0.3.2)
-      io-console (~> 0.5)
-    rspec-core (3.12.1)
-      rspec-support (~> 3.12.0)
-    rspec-expectations (3.12.2)
-      diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.12.0)
-    rspec-mocks (3.12.4)
-      diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.12.0)
-    rspec-rails (6.0.1)
-      actionpack (>= 6.1)
-      activesupport (>= 6.1)
-      railties (>= 6.1)
-      rspec-core (~> 3.11)
-      rspec-expectations (~> 3.11)
-      rspec-mocks (~> 3.11)
-      rspec-support (~> 3.11)
-    rspec-support (3.12.0)
-    thor (1.2.1)
-    timeout (0.3.2)
-    tzinfo (2.0.6)
-      concurrent-ruby (~> 1.0)
-    websocket-driver (0.7.5)
-      websocket-extensions (>= 0.1.0)
-    websocket-extensions (0.1.5)
-    zeitwerk (2.6.7)
-
-PLATFORMS
-  x86_64-linux
-
-DEPENDENCIES
-  debug
-  meta-api!
-  puma (~> 5.0)
-  rails (~> 7.0.4)
-  rspec-rails (~> 6.0.0)
-  tzinfo-data
-
-RUBY VERSION
-   ruby 3.1.2p20
-
-BUNDLED WITH
-   2.3.17

data/examples/rails_app/README.md

@@ -1,11 +0,0 @@
-# 测试 Rails 插件
-
-这个项目作为 meta-api 框架用作 Rails 插件的测试项目。请按照以下命令运行：
-
-```bash
-# 安装 gems
-$ bundle install
-
-# 运行测试
-$ bin/rails test
-```

data/examples/rails_app/Rakefile

@@ -1,6 +0,0 @@
-# Add your own tasks in files placed in lib/tasks ending in .rake,
-# for example lib/tasks/capistrano.rake, and they will automatically be available to Rake.
-
-require_relative "config/application"
-
-Rails.application.load_tasks

data/examples/rails_app/app/controllers/application_controller.rb

@@ -1,7 +0,0 @@
-class ApplicationController < ActionController::API
-  include Meta::Rails::Plugin
-
-  rescue_from Meta::Errors::ParameterInvalid do |e|
-    render json: e.errors, status: :bad_request
-  end
-end

data/examples/rails_app/app/controllers/data_controller.rb

@@ -1,63 +0,0 @@
-class DataController < ApplicationController
-  route '/parse_params', :post do
-    params do
-      param :q, in: 'query'
-      param :user, required: true do
-        param :name, type: 'string', default: 'Jim'
-        param :age, type: 'integer', default: 18
-        param :foo, param: false
-      end
-    end
-  end
-  def parse_params
-    render json: { params_on_schema: params_on_schema }
-  end
-
-  route '/render_hash', :post do
-    status 200 do
-      expose :user, required: true do
-        expose :name, type: 'string', default: 'Jim'
-        expose :age, type: 'integer', default: 18
-      end
-    end
-    status 201 do
-      expose :user, required: true do
-        expose :name, type: 'string', default: 'Jack'
-        expose :age, type: 'integer', default: 20
-      end
-    end
-  end
-  def render_hash
-    render json_on_schema: { 'user' => params[:user].to_unsafe_h }, status: params[:status] || 200, scope: 'foo'
-  end
-
-  route '/render_object', :post do
-    status 200 do
-      expose :user, required: true do
-        expose :name, type: 'string', default: 'Jim'
-        expose :age, type: 'integer', default: 18
-      end
-    end
-  end
-  def render_object
-    user = Object.new
-    def user.name; 'Jim'; end
-    def user.age; 18; end
-    render json_on_schema: { 'user' => user }
-  end
-
-  route '/render_with_options', :post do
-    status 200 do
-      expose :user, required: true do
-        expose :a, value: -> { @a }
-        expose :b, scope: 'foo'
-        expose :c, scope: 'bar'
-        expose :d, default: 'd', render: false
-      end
-    end
-  end
-  def render_with_options
-    @a = 'aa'
-    render json_on_schema: { 'user' => params[:user].to_unsafe_hash }, scope: 'foo'
-  end
-end

data/examples/rails_app/app/controllers/swagger_controller.rb

@@ -1,13 +0,0 @@
-class SwaggerController < ApplicationController
-  def get_spec
-    # 需要提前加载控制器常量，如以下两种方式：
-    # - Rails.application.eager_load!
-    # - Dir.glob(Rails.root.join('app', 'controllers', '**', '*.rb')).each { |f| require f }
-    #
-    # 这里仅仅仅仅使用了 require_relative
-    require_relative 'data_controller'
-
-    doc = Meta::Rails::Plugin.generate_swagger_doc(ApplicationController)
-    render json: doc
-  end
-end

data/examples/rails_app/bin/rails

@@ -1,4 +0,0 @@
-#!/usr/bin/env ruby
-APP_PATH = File.expand_path("../config/application", __dir__)
-require_relative "../config/boot"
-require "rails/commands"

data/examples/rails_app/bin/rake

@@ -1,4 +0,0 @@
-#!/usr/bin/env ruby
-require_relative "../config/boot"
-require "rake"
-Rake.application.run