meta-api 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7364c618306dc9d04e6e08784670157e64b57f3f90b1828a259ba713268bb281
-  data.tar.gz: 00d25192ac7e4b4c733f1aa0d44a2424290d2bc4e290ca99d810686b744ec102
+  metadata.gz: 9b4cc662a6a580592192bcc29cd4367249d1bbba4678aee0f95d75d9ff01c219
+  data.tar.gz: 5bd5ed38531f286ba422a57b8da12aceb0c13a063be1d5c0895c5073abd5a868
 SHA512:
-  metadata.gz: 62eabc56bc4ef76f76cb131f5b901a32875e12b8905857529307dee1acd0a4a354e2822f622f9ef43939444e89e08933e025404050a4347a77fbf169f8a7fe9f
-  data.tar.gz: 6692c9733a12d3acccc18d1cf6227a084c926dfd69b4acaae872e553683b4e70ca85d1aca874d87c169be1c2a68ca51e62ede1c142ef070829f508b7c2820426
+  metadata.gz: b54219704c980114719f6cd9d53d1d77036a194eddd991610b88fe36f52ecf9e04abccfbfaad0d9acd527ba8edc294b333ca403752ff6a0a0f753c30e93d22cd
+  data.tar.gz: 564d6e0dfcae8a11aa59bc740e7fff4901326eff996171539156ae064ce205173c548f295e6d0d8cb085fd4de3b829c7141e5cff5aa343e658f8b2475b004d02

data/.gitignore

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

data/CHANGELOG.md

@@ -1,6 +1,11 @@
 # 更新日志
 
-## V0.0.2（2023 年 3 月 8 日）
+## 0.0.3（2023 年 4 月 4 日）
+
+1. 添加两个新的选项 `ref:` 和 `dynamic_ref:`，以便后期取代 `using:`.
+2. 提供 Rails 插件。
+
+## 0.0.2（2023 年 3 月 8 日）
 
 1. 添加两个配置项，适合生产环境下使用，用以关闭渲染时的数据验证验证。
 2. 添加对多态实体的支持。

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    meta-api (0.0.2)
+    meta-api (0.0.3)
 
 GEM
   remote: https://gems.ruby-china.com/

data/README.md

@@ -17,7 +17,7 @@ $ git clone https://github.com/yetrun/web-frame-example.git
 在 Gemfile 中添加：
 
 ```ruby
-gem 'meta-api', '~> 0.0.1' # Meta 框架处于快速开发阶段，引入时应尽量固定版本
+gem 'meta-api', '~> 0.0.3' # Meta 框架处于快速开发阶段，引入时应尽量固定版本
 ```
 
 然后在 Ruby 代码中引用：
@@ -26,6 +26,8 @@ gem 'meta-api', '~> 0.0.1' # Meta 框架处于快速开发阶段，引入时应
 require 'meta/api'
 ```
 
+> 或者可嵌入到 Rails 项目中使用，参见[为 Rails 项目带来参数验证效果](docs/Rails.md)。
+
 ## 快速上手
 
 ### 定义 API
@@ -37,7 +39,7 @@ class NotesAPI < Meta::Application
   get '/notes' do
     title '查看笔记列表'
     status 200 do
-      expose :notes, type: 'array', using: NoteEntity
+      expose :notes, type: 'array', ref: NoteEntity
     end
     action do
       render :notes, Note.all
@@ -47,10 +49,10 @@ class NotesAPI < Meta::Application
   post '/notes' do
     title '创建新的笔记'
     params do
-      param :note, type: 'object', using: NoteEntity
+      param :note, type: 'object', ref: NoteEntity
     end
     status 201 do
-      expose :note, type: 'object', using: NoteEntity
+      expose :note, type: 'object', ref: NoteEntity
     end
     action do
       note = Note.create!(params[:note])
@@ -65,7 +67,7 @@ class NotesAPI < Meta::Application
       param :id, type: 'integer'
     end
     status 200 do
-      expose :note, type: 'object', using: NoteEntity
+      expose :note, type: 'object', ref: NoteEntity
     end
     action do
       note = Note.find(params[:id])
@@ -76,10 +78,10 @@ class NotesAPI < Meta::Application
   put '/notes/:id' do
     title '更新笔记'
     params do
-      param :note, type: 'object', using: NoteEntity
+      param :note, type: 'object', ref: NoteEntity
     end
     status 200 do
-      expose :note, type: 'object', using: NoteEntity
+      expose :note, type: 'object', ref: NoteEntity
     end
     action do
       note = Note.find(params[:id])

data/docs/Rails.md

@@ -0,0 +1,61 @@
+# 作为 Rails 插件
+
+## 安装
+
+首先，你需要将其安装在 Rails 项目中：
+
+```ruby
+gem 'meta-api', '~> 0.0.3' # 0.0.3 版本以上才提供 Rails 插件功能
+```
+
+在 config/initializers 目录下创建一个文件，例如 `meta_rails_plugin.rb`，并写入：
+
+```ruby
+require 'meta/rails'
+
+Meta::Rails.setup
+```
+
+在 `application_controller.rb` 下加入：
+
+```ruby
+class ApplicationController < ActionController::API
+  # 引入插件，同时引入 route 宏、params_on_schema 方法、json_on_schema 渲染器
+  include Meta::Rails::Plugin
+
+  # 处理参数验证错误
+  rescue_from Meta::Errors::ParameterInvalid do |e|
+    render json: e.errors, status: :bad_request
+  end
+end
+```
+
+这样，一切就准备好了。
+
+## 示例
+
+接口定义：
+
+```ruby
+class UsersController < ApplicationController
+  route '/users', :post do
+    params do
+      param :user, required: true do
+        param :name, type: 'string'
+        param :age, type: 'integer'
+      end
+    end
+  end
+  def create
+    user = User.create!(params_on_schema[:user])
+    render json_on_schema: user
+  end
+end
+```
+
+生成 Swagger 文档：
+
+```ruby
+Rails.application.eager_load! # 需要提前加载所有常量
+Meta::Rails::Plugin.generate_swagger_doc(ApplicationController)
+```

data/docs//345/246/202/344/275/225/350/264/241/347/214/256.md

@@ -0,0 +1,10 @@
+# 如何贡献
+
+## 发布 Gem
+
+执行两条命令：
+
+```bash
+$ gem build meta-api.gemspec
+$ gem push meta-api-x.x.x.gem
+```

data/docs//346/225/231/347/250/213.md

@@ -2,7 +2,7 @@
 
 现有的 Web API 框架并不关注文档的问题，文档往往是作为插件挂载到框架上的。但是，文档和业务实现并不需要割裂开，它们在很大程度上应该是耦合在一起的。比方说，某个接口我定义了参数如此，就该自动生成一致的文档向前端告知；同样，当我提供了文档是如此后，我的接口实现就改自动地约束为这样实现。
 
-Meta 框架（暂定名）天生就是将文档和实现统一起来的，并始终致力于此（如果真的有什么不一致或者不到位的地方，那只能说框架实现上尚有欠缺，并不能从思想上说本该如此）。Meta 框架与 Swagger 合作，致力于产生符合 Restful 和社区规范的文档格式。它提供了几乎完整的描述接口信息的宏命令，并且在描述接口的同时就能基本实现接口的一些约束，其中最重要的莫过于对参数和返回值的声明。
+Meta 框架天生就是将文档和实现统一起来的，并始终致力于此（如果真的有什么不一致或者不到位的地方，那只能说框架实现上尚有欠缺，并不能从思想上说本该如此）。Meta 框架与 Swagger 合作，致力于产生符合 Restful 和社区规范的文档格式。它提供了几乎完整的描述接口信息的宏命令，并且在描述接口的同时就能基本实现接口的一些约束，其中最重要的莫过于对参数和返回值的声明。
 
 ## 准备工作
 
@@ -771,15 +771,15 @@ class UserEntity < Meta::Entity
 end
 ```
 
-然后在 `params` 和 `status` 内部使用 `using` 引用这个实体：
+然后在 `params` 和 `status` 内部使用 `ref` 引用这个实体：
 
 ```ruby
 params do
-  param :user, using: UserEntity
+  param :user, ref: UserEntity
 end
 
 status 200 do
-  expose :user, using: UserEntity
+  expose :user, ref: UserEntity
 end
 ```
 
@@ -789,11 +789,11 @@ end
 > 
 > ```ruby
 > params do
->   property :user, using: UserEntity
+>     property :user, ref: UserEntity
 > end
 > 
 > status 200 do
->   property :user, using: UserEntity
+>     property :user, ref: UserEntity
 > end
 > ```
 
@@ -805,7 +805,7 @@ end
 
 ```ruby
 params do
-  param :users, type: "array", using: UserEntity
+  param :users, type: "array", ref: UserEntity
 end
 ```
 
@@ -887,7 +887,7 @@ end
 ```ruby
 get '/articles' do
   status 200 do
-    expose :articles, using: ArticleEntity
+    expose :articles, ref: ArticleEntity
   end
   action do
     articles = Article.all
@@ -901,7 +901,7 @@ end
 ```ruby
 get '/articles/:id' do
   status 200 do
-    expose :article, using: ArticleEntity
+    expose :article, ref: ArticleEntity
   end
   action do
     article = Article.find(request.params['id'])
@@ -915,7 +915,7 @@ end
 ```ruby
 get '/articles/:id' do
   status 200 do
-    expose :article, using: ArticleEntity.lock_scope('full')
+    expose :article, ref: ArticleEntity.lock_scope('full')
   end
   action do
     article = Article.find(request.params['id'])
@@ -929,14 +929,14 @@ end
 ```ruby
 post '/articles' do
   params do
-    param :article, using: ArticleEntity.lock_scope('on_create')
+    param :article, ref: ArticleEntity.lock_scope('on_create')
   end
   ...
 end
 
 put '/articles/:id' do
   params do
-    param :article, using: ArticleEntity.lock_scope('on_update')
+    param :article, ref: ArticleEntity.lock_scope('on_update')
   end
   ...
 end
@@ -994,7 +994,7 @@ end
 
 ```ruby
 params do
-  param :article, using: ArticleEntity
+  param :article, ref: ArticleEntity
 end
 ```
 
@@ -1034,10 +1034,10 @@ end
 
 ### 多态参数和返回值
 
-定义属性时可定义多态类型，`using` 选项可接受一个块，它根据值来返回指定的类型：
+定义属性时可定义多态类型，`dynamic_ref` 选项可接受一个块，它根据值来返回指定的类型：
 
 ```ruby
-property :target, using: ->(value) {
+property :target, dynamic_ref: ->(value) {
   # 根据 value.target_type 值返回实体类型
   # 例如，value.target_type == 'UserEntity'，将返回 UserEntity 类
   value.target_type.constantize
@@ -1047,7 +1047,7 @@ property :target, using: ->(value) {
 或者接受一个 Hash，这时可提供 `one_of` 选项为文档生成提供加成：
 
 ```ruby
-property :animal, using: {
+property :animal, dynamic_ref: {
   one_of: [CatEntity, DogEntity, PigEntity],
   resolve: ->(value) { value.animal_type.constantize }
 }
@@ -1098,7 +1098,7 @@ Meta.config.render_validation = false      # 渲染时不执行数据验证
 
 ```ruby
 params do
-  param :user, using: UserEntity
+  param :user, ref: UserEntity
 end
 
 
@@ -1109,7 +1109,7 @@ end
 但也可以将包裹的外层字段去掉，即将 `UserEntity` 直接用在顶层：
 
 ```ruby
-params using: UserEntity
+params ref: UserEntity
 
 
 # 接受如下格式的数据
@@ -1119,7 +1119,7 @@ params using: UserEntity
 这个方案同时也支持数组：
 
 ```ruby
-params type: 'array', using: UserEntity
+params type: 'array', ref: UserEntity
 
 # 接受如下格式的数据
 [
@@ -1190,12 +1190,12 @@ end
 
 > **小提示：**还有一种调用方式 `params(:raw)`，它返回无任何转换逻辑的原生参数。它与 `request.params` 的行为一致。
 
-> **大提示：**如果你是通过 `using:` 引用一个实体定义，另一个更符合语义的方式是使用 `lock` 方法。
+> **大提示：**如果你是通过 `ref:` 引用一个实体定义，另一个更符合语义的方式是使用 `lock` 方法。
 >
 > ```ruby
 > patch '/users/:id' do
 >   params do
->     param :user, using: UserEntity.lock(:discard_missing, true)
+>     param :user, ref: UserEntity.lock(:discard_missing, true)
 >   end
 >   action do
 >     user = User.find(params['id'])

data/examples/rails_app/.gitattributes

@@ -0,0 +1,5 @@
+# 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

@@ -0,0 +1,23 @@
+# 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

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

data/examples/rails_app/.ruby-version

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

data/examples/rails_app/Gemfile

@@ -0,0 +1,29 @@
+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

@@ -0,0 +1,190 @@
+PATH
+  remote: /home/run/workspace/personal/web-frame
+  specs:
+    meta-api (0.0.2)
+
+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

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

data/examples/rails_app/Rakefile

@@ -0,0 +1,6 @@
+# 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

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