meta-api 0.0.4 → 0.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bc6f6c3dddfd1e683cae7147be60bd7ead57e46b097700fc1db4113d12f08965
-  data.tar.gz: 476caee521969debd84614433ab41be89fbe7d1e5b074f46a6c8df40ca2d2c43
+  metadata.gz: b4385e82bdaec80e15adc4b62b1259f30125720452e579d84a45c79471c2d9cb
+  data.tar.gz: f3b9baa683d4a757eabbcc9c13e86f133741f941f75c92bf8e28999d17f29653
 SHA512:
-  metadata.gz: 3e213a983004b7fed1d15c2e0b41c9746584d259af6f969c631669b7efbb63f5573ee67b61ca5cb95888738925ca525e2ae4045502a7998c57c96432c12e3fd7
-  data.tar.gz: b575cf5145a3693ceb14296178c25c1ab1f8bf23e2a7dac92e9cc131a82dd79649d101f066c716069a5cb99114c138842b7bde89734790f217095fd459bf8fb4
+  metadata.gz: 29e7fa33cae933c185cad5ea6bc5e0a9e460f549b5ea8bd12a6217b93e473d61a9cd5eaba2f803c28a5a55710a3668db80c42ad656b526cfb8604e50cdb42721
+  data.tar.gz: c7774b6feb64e9646017a7034082ab81b9fcf9a3928450edd725192671126a472941da314f64eb5c798a253eec6c82a99ff0701db6eacbda31cff42b6a605de0

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 # 更新日志
 
+## 0.0.6（2023 年 5 月 26 日）
+
+1. 添加了 Meta::Execution#abort_execution! 方法。
+2. 重新规范响应体的 application/json 设定，尽可能不过分设定。
+3. 修复了若干实现上和文档的 bug.
+
+## 0.0.5（2023 年 4 月 27 日）
+
+1. 调整了 `around` 钩子的执行顺序，它与 `before` 钩子共同定义顺序。
+2. 修复了若干 bug.
+
 ## 0.0.4（2023 年 4 月 18 日）
 
 1. `Application` 添加 `.around` 宏。

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    meta-api (0.0.4)
+    meta-api (0.0.5)
 
 GEM
   remote: https://gems.ruby-china.com/
@@ -63,4 +63,4 @@ DEPENDENCIES
   rspec
 
 BUNDLED WITH
-   2.3.17
+   2.3.7

data/README.md

@@ -1,12 +1,12 @@
 # Meta 框架
 
-Meta 框架是一个适用于 Web API 的后端框架，采用 Ruby 语言编写。正如它的名字，它是用定义“元”信息的方式实现 API，同时一份符合 Open API 语义的文档也能同步生成。
+Meta 框架是一个用于开发 Web API 的后端框架，采用 Ruby 语言编写。正如它的名字，它是用定义“元”信息的方式实现 API，同时生成一份符合 Open API 规格的接口文档。
 
 > 有关框架名称的由来，阅读[框架的名称由来](docs/名称由来.md)。
 
 ## 脚手架
 
-你可直接使用我的脚手架项目上手体验：
+可直接使用我的[脚手架](https://github.com/yetrun/web-frame-example)项目上手体验：
 
 ```bash
 $ git clone https://github.com/yetrun/web-frame-example.git
@@ -17,7 +17,7 @@ $ git clone https://github.com/yetrun/web-frame-example.git
 在 Gemfile 中添加：
 
 ```ruby
-gem 'meta-api', '~> 0.0.3' # Meta 框架处于快速开发阶段，引入时应尽量固定版本
+gem 'meta-api', '~> 0.0.5' # Meta 框架处于快速开发阶段，引入时应尽量固定版本
 ```
 
 然后在 Ruby 代码中引用：
@@ -26,9 +26,9 @@ gem 'meta-api', '~> 0.0.3' # Meta 框架处于快速开发阶段，引入时应
 require 'meta/api'
 ```
 
-> 或者可嵌入到 Rails 项目中使用，参见[为 Rails 项目带来参数验证效果](docs/Rails.md)。
+> 或者可嵌入到 Rails 项目中使用，参考[为 Rails 项目带来参数验证效果](docs/Rails.md)。
 
-## 快速上手
+## 快速一览
 
 ### 定义 API
 
@@ -52,12 +52,12 @@ class NotesAPI < Meta::Application
       param :note, type: 'object', ref: NoteEntity
     end
     status 201 do
-      expose :note, type: 'object', ref: NoteEntity
+      expose :note, type: 'object', ref: NoteEntity.lock_scope('full')
     end
     action do
       note = Note.create!(params[:note])
       response.status = 201
-      render :note, note, scope: 'full'
+      render :note, note
     end
   end
 
@@ -67,7 +67,7 @@ class NotesAPI < Meta::Application
       param :id, type: 'integer'
     end
     status 200 do
-      expose :note, type: 'object', ref: NoteEntity
+      expose :note, type: 'object', ref: NoteEntity.lock_scope('full')
     end
     action do
       note = Note.find(params[:id])
@@ -81,7 +81,7 @@ class NotesAPI < Meta::Application
       param :note, type: 'object', ref: NoteEntity
     end
     status 200 do
-      expose :note, type: 'object', ref: NoteEntity
+      expose :note, type: 'object', ref: NoteEntity.lock_scope('full')
     end
     action do
       note = Note.find(params[:id])
@@ -92,6 +92,7 @@ class NotesAPI < Meta::Application
 
   delete '/notes/:id' do
     title '删除笔记'
+    status 204
     action do
       note = Note.find(params[:id])
       note.destroy!
@@ -107,18 +108,12 @@ end
 
 ```ruby
 class NoteEntity < Meta::Entity
-  property :id, type: 'integer', param: false
+  property :id, type: 'integer', param: false # 不作为参数传递
   property :title, type: 'string'
-  property :content, type: 'string', render: { scope: 'full' }
+  property :content, type: 'string', render: { scope: 'full' } # 列表页接口不返回此字段
 end
 ```
 
-我们发现了一些特殊的定义：
-
-- 标记 `id` 的 `param` 选项为 `false`，它不作为参数传递。
-
-- 标记 `content` 在 `render` 下的 `scope`，当且仅当显示传递 `scope` 为 `false` 时才会渲染此字段。（对比 *查看笔记列表* 和 *查看笔记* 接口）
-
 ### 生成 API 文档
 
 通过主动调用以下的方法可以生成 Open API 的规格文档：
@@ -127,20 +122,32 @@ end
 NotesAPI.to_swagger_doc
 ```
 
-该 Open API 文档是 JSON 格式，可以在 Swagger UI 下预览效果。如果你不想寻找提供 Swagger UI 服务的站点，也不想自己搭建，可以直接使用我的：
+该 Open API 文档是 JSON 格式，可以在 Swagger UI 下预览效果。如果也不乐意自己搭建 Swagger UI，可以直接使用在线的：
 
 > http://openapi.yet.run/playground
 
 ### 将模块挂载在 Rack 下运行
 
-API 模块同时也是一个 Rack 中间件，它可以挂载在 Rack 下运行：
+API 模块同时也是一个 Rack 中间件，它可以挂载在 Rack 下运行。假设以上文件分别位于 `notes_api.rb` 和 `note_entity.rb`，在项目下新建文件 `config.ru`，并写入：
 
 ```ruby
-# config.ru
+require 'meta/api'
+require_relative 'notes_api'
+require_relative 'note_entity'
+
+# 将文档挂载到 /api_spec 锚点下
+map '/api_spec' do
+  run ->(env) { 
+    [200, { 'CONTENT_TYPE' => 'application/json' }, [JSON.generate(NotesAPI.to_swagger_doc)]]
+    }
+end
 
+# 启动 NotesAPI 中定义的接口
 run NotesAPI
 ```
 
+然后执行命令：`bundle exec rackup`，接口即可启动。
+
 ## 文档
 
 - [教程](docs/教程.md)
@@ -148,7 +155,11 @@ run NotesAPI
 
 ## 支持
 
-加 QQ 群（489579810）可获得实时答疑。
+你可以通过以下途径获得支持：
+
+1. 通过 GitHub 提交 [ISSUE](https://github.com/yetrun/web-frame/issues)
+2. 通过 QQ 群（489579810）获得实时答疑
+3. 对本项目提交 [Pull Request](https://github.com/yetrun/web-frame/pulls)
 
 ## License
 

data/config/locales/zh-CN.yml

@@ -1,6 +1,14 @@
 zh-CN:
   json_schema:
+    type_names:
+      basic: "基本类型"
+      array: "数组类型"
     errors:
-      required: '未提供'
-      format: '格式不正确'
-      allowable: '不在允许的值范围内'
+      required: "未提供"
+      format: "格式不正确"
+      allowable: "不在允许的值范围内"
+      type_convert:
+        basic: "类型转化失败，期望得到一个 `%{target_type}` 类型，但值 `%{value}` 无法转化"
+        array: "转化为数组类型时期望对象拥有 `to_a` 方法"
+        object: "类型转化失败，期望得到一个 `object` 类型，但值 `%{value}` 是一个%{real_type}"
+        unknown: "未知的目标类型 `%{target_type}`"