meta-api 0.0.5 → 0.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a3fc58de696caf4cf3abade846de9af53bb6491bda575b361461aa67f07d2fb9
-  data.tar.gz: 68d00c2d43086af73a10bbe6bfc103a5ee8611751b01ad2b9c811edf9197438a
+  metadata.gz: b4385e82bdaec80e15adc4b62b1259f30125720452e579d84a45c79471c2d9cb
+  data.tar.gz: f3b9baa683d4a757eabbcc9c13e86f133741f941f75c92bf8e28999d17f29653
 SHA512:
-  metadata.gz: 18cf46619c9f286fe01fbc3b941a6ca5a5e380740ad94e4d6827040cd9c6a014f6249eb13bc609a9f56fe2c15da6e044250f610b0eafdf6202aa9b6a16a0f15b
-  data.tar.gz: edc1532a86fe8776f061cfd1f550392ba280a4e693437b6d6260bfcfce8f0a33d7ae66e6f95250fb8530751307751a53857c0fd2a32a57ec9f8764bf6a9037da
+  metadata.gz: 29e7fa33cae933c185cad5ea6bc5e0a9e460f549b5ea8bd12a6217b93e473d61a9cd5eaba2f803c28a5a55710a3668db80c42ad656b526cfb8604e50cdb42721
+  data.tar.gz: c7774b6feb64e9646017a7034082ab81b9fcf9a3928450edd725192671126a472941da314f64eb5c798a253eec6c82a99ff0701db6eacbda31cff42b6a605de0

data/CHANGELOG.md

@@ -1,6 +1,12 @@
 # 更新日志
 
-## 0.0.5（2023 年 4 月 18 日）
+## 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.

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
@@ -26,9 +26,9 @@ gem 'meta-api', '~> 0.0.5' # 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/docs//346/225/231/347/250/213.md

@@ -1,6 +1,6 @@
 # 教程
 
-现有的 Web API 框架并不关注文档的问题，文档往往是作为插件挂载到框架上的。但是，文档和业务实现并不需要割裂开，它们在很大程度上应该是耦合在一起的。比方说，某个接口我定义了参数如此，就该自动生成一致的文档向前端告知；同样，当我提供了文档是如此后，我的接口实现就改自动地约束为这样实现。
+现有的 Web API 框架并不关注文档的问题，文档往往是作为插件挂载到框架上的。但是，文档和业务实现并不需要割裂开，它们在很大程度上应该是耦合在一起的。比方说，某个接口我定义了参数如此，就该自动生成一致的文档向前端告知；同样，当我提供了文档是如此后，我的接口实现就该自动地约束为这样实现。
 
 Meta 框架天生就是将文档和实现统一起来的，并始终致力于此（如果真的有什么不一致或者不到位的地方，那只能说框架实现上尚有欠缺，并不能从思想上说本该如此）。Meta 框架与 Swagger 合作，致力于产生符合 Restful 和社区规范的文档格式。它提供了几乎完整的描述接口信息的宏命令，并且在描述接口的同时就能基本实现接口的一些约束，其中最重要的莫过于对参数和返回值的声明。
 
@@ -8,340 +8,483 @@ Meta 框架天生就是将文档和实现统一起来的，并始终致力于此
 
 在正式阅读本教程之前，有一些*准备工作*需要提前了解的。
 
-### 一些限制
+### 只接受 JSON
 
-在正式介绍框架能力之前，我先声明一下框架的约束。设定这些约束，主要是因为框架开发尚处于初期阶段，而且精力有限，因此将框架的完成度限定在更小的范围内。
+**只接受格式为 `application/json` 的请求体参数，并且响应实体的格式一律为 `application/json`.**
 
-1. **只接受格式为 `application/json` 的请求参数，并且响应实体的格式一律为 `application/json`.**
-   
-   这在当前的环境下并不算太大的限制，如果你是致力于新项目的开发的话。但是，如果你处理旧项目，并且要求格式为 `application/json` 之外的格式，如 `application/xml`，则框架目前是无能为力的。
-   
-   这中限制只包括请求参数的实体，诸如路径里的参数、或 query 中的参数依然可用，不受该限制。
+这在当前的环境下并不算太大的限制，如果你是致力于新项目的开发的话。但是，如果你处理旧项目，并且要求格式为 `application/json` 之外的格式，如 `application/xml`，则框架目前是不能自动处理的。
 
-2. **由于只能接受 `application/json` 的请求格式，因此你无法使用传统的表单上传方式。**
-   
-   表单上传有它特有的格式名，为 `multipart/form-data`. 因此，用框架提供的行为无法完成表单上传的格式。这并不是说无法完成表单上传的功能，你可能需要处理原生的 `Request` 对象（它是 Rack 架构提供的一个对象，参考 [Rack::Request](https://www.rubydoc.info/gems/rack/Rack/Request)）。同样的，你如果要返回 `application/json` 之外的格式，你需要手动地处理原生的 `Response` 对象（同样也是 Rack 架构提供的一个对象，参考 [Rack::Response](https://www.rubydoc.info/gems/rack/Rack/Response)）。
+这种限制只存在于通过 `params` 宏和 `status` 宏设定了请求体和响应体格式的情况。如果你没有用到这两个宏，那么你还是可以自由定义请求体和响应体的格式，只不过缺少了文档化的支持。自由实现需要用到 [`Rack::Request`](https://www.rubydoc.info/gems/rack/Rack/Request) 类和 [`Rack::Response`](https://www.rubydoc.info/gems/rack/Rack/Response) 类提供的方法，这是 Rack 架构提供的两个包装类，用于简化 HTTP 请求和响应操作。
 
 ### 教程脉络
 
-首先，你将了解定义路由的全部知识。你从其他框架学习的经验也同样适用于本框架，如嵌套路由、before/after 钩子、异常拦截等、以及模块共享和复用等。
+首先，你将学到定义路由的全部知识。换句话说，你该如何具体地*描述*一个接口。一般来说，我们需要描述接口的标题、详述、标签、参数和返回值。
 
-然后，你将了解路由的内部如何定义。换句话说，你该如何具体地*描述*一个接口。一般来说，我们需要描述接口的标题、详述、标签、参数和返回值。
+然后，你将学到命名空间的概念。命名空间用来组织接口的层级结构，并且会用到诸如如路由嵌套、before/after 钩子、异常拦截等概念。
 
-接下来，我们将深入参数和返回值的定义。虽然说前面已经提到参数和返回值的知识，但仅覆盖最简单同时也是最常用的场景。参数和返回值的知识实在是太大了，有必要专门划出一个章节来介绍它。这里提一下，参数和返回值在 Meta 框架里都统一为一个叫做实体的概念，因此你只需要学会定义一种就能够同时定义两者了。
+从命名空间引申出的模块的概念也很重要。模块本身也是一个命名空间，命名空间用到的功能都可以用在模块中。除此之外，模块还用来组织大型应用的结构。最后，模块本身也是一个 Rack 应用，可以直接放在服务器下运行。
 
-最后，将是一个生成文档的方法。虽然它很简单，仅仅是一个方法，但它如此重要以至于我不得不专门划出一个章节来强调它的重要性。说实话将这块内容放在最后我有点不太满意，它是如此重要，开篇就该提到。
+接下来是重点，我们将深入参数和返回值的定义。虽然说前面已经提到参数和返回值的知识，但仅覆盖最简单同时也是最常用的场景。参数和返回值的知识实在是太大了，有必要专门划出一个章节来介绍它。这里提一下，参数和返回值在 Meta 框架里都统一为一个叫做实体的概念，因此你只需要学会定义一种就能够同时定义两者了。
 
-## 模块和路由定义
+最后，将是一个生成文档的方法。虽然它很简单，仅仅是一个方法，但它如此重要以至于我不得不专门划出一个章节来强调它的重要性。
 
-*（我抛弃了 Rack 和中间件的知识，如果你知道它将更好了）*
+文章的最后是特殊用法举例。说实话，我还没想好把它放哪，但它确实列举了几个比较常见的场景。
 
-在 Meta 中，`Meta::Application` 类用来定义一个模块。一个模块同时也是一个应用，将它挂载在 Rack 下可以直接作为一个服务运行。我将它称为模块主要是因为它可以复用（后面你将了解到使用 `apply` 方法复用一个模块）。
+### 继承和宏定义
 
-我们先看一下最简单的 `Meta::Application` 实例：
+在使用 Meta 框架提供的组件时，我们往往先要继承一个类，然后直接在类定义中使用宏命令。所谓的宏命令其实就是一个 Ruby 方法，只不过在 DSL 术语中我们将它称为“宏”。
+
+例如，定义一个 API，我们继承的是 `Meta::Application` 类，然后在类中使用 `route` 宏定义路由：
 
 ```ruby
 class DemoApp < Meta::Application
-  get do
-    title '应用的根路径'
-    action do
-      response.body = ["Hello, world!"]
-    end
+  route '/foo', :get do
+    # ... 具体的宏定义
   end
 end
 ```
 
-*将它挂载在 Rack 下并访问 `http://localhost:9292` 你将看到效果。*
+再比如继承 `Meta::Entity` 定义一个实体，实体内使用 `property` 宏定义属性：
 
-这里，我们只是用 `get` 方法简单地定义了一个 `get /`  路由，并定义了该路由下的标题和实现。该实现没有用到 Meta 框架提供的参数和返回值的概念，只是简单地操纵原生 Rack Response 对象返回一个纯文本格式。
+```ruby
+class UserEntity < Meta::Entity
+  property :name
+  property :age
+end
+```
 
-### 路由定义
+## 路由定义（`route` 宏）
 
-除了 `get` 之外，我们还支持 `post`、`put`、`patch`、`delete` 四个方法。同时后面可跟一个路径表示路的路径：
+在 `Meta::Application` 类内，第一个能做的事情就是定义路由。`route` 方法（以后我们称这种特定的 DSL 方法为“宏”）定义一个具体的路由（即接口）：
 
 ```ruby
 class DemoApp < Meta::Application
-  post do
-    # ...
+  route '/', :get do
+    # 块内定义路由的详细元素
   end
+end
+```
+
+###  HTTP 路径和方法
 
-  put '/foo' do
+`route` 方法接受一个路径字符串和一个 HTTP 方法，并且可接受一个块用于定义路由的详细元素（将在后面讲到）。HTTP 方法我们一共支持五种，包括 `get`、`post`、`put`、`patch`、`delete`. 为此，我们提供了五个便捷方法用于简化 `route` 方法调用的书写，举例：
+
+```ruby
+class DemoApp < Meta::Application
+  get do # 当路径为 `/` 时，路径参数可以省略
     # ...
   end
 
-  patch '/bar' do
+  post '/foo' do
     # ...
   end
 
+  put '/foo/bar' do
+    # ...
+  end
+  
+  patch '/foo/bar' do
+    # ...
+  end
+  
   delete '/foo/bar' do
     # ...
   end
 end
 ```
 
-以上方法只是 `route(path, method, &block)` 的简写，例如 `put '/foo'` 可以完整地写为 `route '/foo', :put`.
+> 因为这种写法更为清晰并且视觉效果更好，教程的以后都用 `get`、`post`、`put`、`patch`、`delete` 五个方法代替 `route` 方法的调用。除非是只用到路径而不关心 HTTP 方法的情形。
 
-### 路径定义
+### 通配符路径
 
-路径中可以包括参数：
+当定义路由 `route /foo/bar` 时，它匹配的是完整的路径 `/foo/bar`. 当你需要匹配一堆路径时，需要为路由加上通配符符号。`:` 和 `*` 是通配符符号的两种，前者匹配一个部分，后者尽可能多地匹配剩余的部份。这么说如果没说清楚，我举两个例子即可明白：
 
 - `/foo/:id`：它将匹配诸如 `/foo/1`、`/foo/bar` 等路径，但不能匹配 `/foo/a/b/c` 这样的路径。
 - `/foo/*path`：它可以匹配 `/foo`、`/foo/bar`、`/foo/a/b/c` 等格式的路径。
 
-凡是路径中带有命名参数的都能被访问到，例如 `request.params['id']`、`request.params['path']` 。（注意，方括号内一定得是字符串）
+> 通配符符号后面的单词（`id` 和 `path`）是参数名称，它将路由中与其匹配的部分放到参数中可访问。这里先提一下，通过 `request.params['id']`、`request.params['path']` 可以访问到路由当中匹配的部分。
 
-如果你不需要后续访问到参数，可以忽略命名。不过我认为加个名字语义上更加友好，尽管你不必用到。
+如果你不需要后续访问到参数，可以忽略命名：
 
 - `/foo/:`
 - `/foo/*`
 
-在定义参数时要学会不拘一格，试想一下以下的路径定义将匹配哪些：
+再举两个路由参数的示例：
 
-- `/foo/:id/bar`
-- `/foo/*/bar`
+- `/foo/:id/bar`：匹配诸如 `/foo/1/bar`、`/foo/2/bar` 等路径
+- `/foo/*/bar`：匹配 `/foo/bar`、`/foo/a/bar`、`/foo/a/b/bar`、`/foo/a/b/c/bar` 等格式的路径。
 
-### 嵌套路由
+### 定义路由的元信息（`meta` 宏）
 
-用 `route` 方式定义的路由是不支持嵌套的。有一个专门为定义嵌套路由而存在的命令：`namespace`.
+在 `route` 宏内部，可使用两个宏： `meta` 宏定义路由的元信息，`action` 宏定义路由的执行逻辑。
 
-```ruby
-class DemoApp < Meta::Application
-  namespace '/user' do
-    get do
-      title '获取用户详情'
-    end
+首先，通过 `meta` 宏定义路由的“元”信息。注意，“元”信息的作用是双向的，既可以定义接口的文档，也可以约束接口的行为。例如，在 ` meta` 宏内定义参数：
 
-    put do
-      title '更新用户详情'
+```ruby
+post '/users' do
+  meta do
+    params do
+      param :name, type: 'string', description: '姓名'
+      param :age, type: 'integer', description: '年龄'
     end
   end
 end
 ```
 
-### 钩子
+它会产生两个方面的效果：
 
-*（如果不涉及到钩子和异常拦截，嵌套路由将毫无意义。）*
+1. 文档方面：接口文档的参数部分会暴露出两个参数：`name`、`age`，并声明它的类型和描述信息。
+2. 业务逻辑方面：业务代码执行时，通过标准的方法获取参数时会对参数作校验。这里面它只会提取出参数的两个字段（`name` 和 `age`），并对它们俩的类型作校验。如果参数不符合定义，会向客户端抛出一个错误。
 
-正如名字所表达的那样，`before` 就是 before 钩子，`after` 就是 after 钩子。将以上例子加上 `before` 钩子将如下：
+#### `meta` 宏一览
 
-```ruby
-class DemoApp < Meta::Application
-  namespace '/user' do
-    before do
-      @user = get_user
-    end
+`meta` 宏内部现在只提供了以下五个方法：
 
-    get do
-      title '获取用户详情'
+```ruby
+post '/users' do
+  meta do
+    title '创建用户'
+    description '接口的详细描述'
+    tags ['User'] # 定义接口的 Tag，传递一个数组
+    params do
+      # 内部定义参数结构
     end
-
-    put do
-      title '更新用户详情'
+    status 200 do
+      # 内部定义返回值结构
     end
   end
 end
 ```
 
-同时还支持 `around` 钩子（*试验特性*）：
+以上，`title`、`description`、`tags` 宏分别定义接口的标题、描述信息和标签列表。`params` 和 `status` 宏定义接口的参数和返回值，其内部定义比较复杂，将在后面详细讲解。
 
-```ruby
-class DemoApp < Meta::Application
-  before { puts 1 }
-  around { |next_action|
-     puts 2
-     next_action.execute(self)
-     puts 7
-  }
-  before { puts 3 }
-  after { puts 5 }
-  after { puts 6 }
+#### `meta` 宏展开
+
+`meta` 宏可以展开定义，亦即可以直接在 `route` 定义内部直接使用 `meta` 宏定义的语法，它是 `route` 定义内部提供的一种快捷方式：
 
-  get '/request' do
-    puts 4
+```ruby
+post '/users' do
+  title '创建用户'
+  description '接口的详细描述'
+  tags ['User'] # 定义接口的 Tag，传递一个数组
+  params do
+    # 内部定义参数结构
+  end
+  status 200 do
+    # 内部定义返回值结构
   end
 end
 ```
 
-所有钩子的执行顺序是：
+> 由于展开定义的方式写起来更加便捷，因此后面的教程示例都将采取这样的写法。
 
-1. `before` 钩子和 `around` 钩子的前半部分，按照定义的顺序执行
-2. 然后执行路由方法。
-3. 然后执行 `after` 钩子，按照定义的顺序执行。
-4. 最后执行 `around` 钩子的后半部分，按照定义的逆序执行。
+### 定义路由的执行逻辑（`action` 宏）
 
-### 异常拦截
+`action` 宏定义业务代码部分。将上面的 `POST /users` 接口的逻辑实现定义完全，大概率是以下这个样子：
 
-在 `namespace` 中使用 `rescue_error` 拦截异常。
+```ruby
+post '/users' do
+  # ... 定义路由的 meta 部分
+  action do
+    user = User.create!(params[:user])
+    render :user, user
+  end
+end
+```
+
+其中，用到的 `params` 方法和 `render` 方法将在后面讲到。
+
+## 层次化地定义路由（`namespace` 宏）
+
+### 使用 `namespace` 宏定义嵌套路由
 
 ```ruby
 class DemoApp < Meta::Application
-  namespace '/user' do
-    rescue_error RecordNotFound do |e|
-      response.status = 404
-      response.body = ["所访问的资源不存在"]
+  get do # 匹配 GET /
+    # ...
+  end
+
+  namespace '/foo' do
+    get do # 匹配 GET /foo
+      # ...
+    end
+
+    post '/bar' do # 匹配 POST /foo/bar
+      # ...
+    end
+    
+    namespace '/baz' do
+      # ... 匹配前缀为 /foo/baz
     end
   end
 end
 ```
 
-### 关于嵌套的进一步说明
+`namespace` 宏是定义父级结构的，它不能定义到具体的路由，它的内部需要有 `namespace` 宏或 `route` 宏定义更具体的结点。**`namespace` 宏匹配的是路径的前缀。**
+
+而 `route` 宏是最深层次的结构，它定义的是具体的路由和它的行为，它的内部不能有 `namesapce` 宏及 `route` 宏。**`route` 宏要匹配完整的路径。**
+
+> 为什么要定义一个 `namespace` 宏，它不仅仅是减少路径的重复代码这么简单。综合来讲，`namespace` 宏有如下作用：
+>
+> 1. 通过组合 `namespace` 和 `route` 宏来定义应用的层次结构。
+> 2. `namespace` 内可定义钩子，用于公共的运行逻辑。
+> 3. 可定义 `namespace` 级的异常拦截处理方法。
+> 4. 在 `namespace` 定义 `meta` 宏，可定义公共的“元”信息。
+
+### 钩子
+
+`namesapce` 内提供了两种钩子：`before`、`after`. 它在整个 `namespace` 层级执行一遍。
 
-钩子只在当前作用域和它的子作用域下起作用，父级作用域不会起作用。
+正如名字所表达的那样，`before` 在 `action` 宏之前执行，`after` 在 `action` 宏之后执行。
 
 ```ruby
 class DemoApp < Meta::Application
   namespace '/foo' do
     before do
-      @foo = 'foo'
+      puts 1
     end
 
+    after do
+      puts 2
+    end
+    
     get do
       action do
-        p @foo # 'foo'
-        p @bar # nil
+        puts 3
       end
     end
 
-    namespace '/bar' do
-      before do
-          @foo = 'foo'
-      end
-
-      get do
-        action do
-          p @foo # 'foo'
-          p @bar # 'bar'
-        end
+    put do
+      action do
+        puts 4
       end
     end
   end
 end
 ```
 
-异常拦截先拦截子作用域；如果拦截失败则继续在父作用域下拦截。
+当用户访问 `GET /foo` 接口时，依次打印数字 `1`、`3`、`2`；当用户访问 `PUT /foo` 接口时，依次打印数字 `1`、`4`、`2`.
+
+#### `around` 钩子（实验特性）
+
+Meta 框架同时还支持 `around` 钩子， `around` 钩子会包裹 `action` 执行：
 
 ```ruby
 class DemoApp < Meta::Application
   namespace '/foo' do
-    rescue_error ErrorOne do
-      # 它将捕获 '/foo' 路由下的异常
+    around do |next_action|
+      puts 1
+      next_action.execute(self)
+      puts 2
+    end
+    
+    get do
+      action do
+        puts 3
+      end
     end
 
-    namespace '/bar' do
-      rescue_error ErrorTwo do
-        # 它将捕获 '/foo/bar' 路由下的异常
+    put do
+      action do
+        puts 4
       end
     end
   end
 end
 ```
 
-### 模块
+同样的，当用户访问 `GET /foo` 接口时，依次打印数字 `1`、`3`、`2`；当用户访问 `PUT /foo` 接口时，依次打印数字 `1`、`4`、`2`.
+
+> `around` 钩子现在还处于实验阶段，不建议实际开发中使用。当 `around` 钩子混合定义 `before`、`after` 钩子时，其执行的顺序比较混乱。而且，现在的 `around` 钩子还无法覆盖参数解析和返回值渲染的过程，这让它们的应用范围受到限制。当需要完整覆盖接口执行的全周期时，推荐使用 Rack 的中间件。最后，一定要在恰当的时机执行 `next_action.execute(self)`，否则后续的动作将不会得到执行。 `next_action.execute(self)` 调用稍显繁琐，不够优雅。
+
+#### 所有钩子的执行顺序
+
+如果只包含 `before` 和 `after` 钩子，则执行的顺序是：
 
-`Meta::Application` 可以像 `namespace` 一样，定义路由、设置 before/after 钩子、拦截异常等。将以上例子里 `/foo` 的部分抽成一个模块如下：
+1. `before` 钩子先执行，按照定义的顺序；
+2. 接着执行 `action` 定义的块；
+3. 最后执行 `after` 钩子，按照定义的顺序。
+
+举例（以下按照 `1`、`2`、`3` 的数字顺序执行）：
 
 ```ruby
-class Foo < Meta::Application
-  rescue_error ErrorOne do
-    # 它将捕获 '/foo' 路由下的异常
-  end
+class DemoApp < Meta::Application
+  namespace '/foo' do
+    before { puts 1 }
+    before { puts 2 }
+    after { puts 4 }
+    after { puts 5 }
 
-  namespace '/bar' do
-    rescue_error ErrorTwo do
-      # 它将捕获 '/foo/bar' 路由下的异常
+    get '/request' do
+      puts 3
     end
   end
 end
 ```
 
-为达到同样的效果，我们可以在 `DemoApp` 下应用这个模块：
+如果还包含 `around` 钩子，则会复杂一些，但大体上是：
+
+1. 最先执行的是 `before` 钩子以及 `around` 钩子的前半部分，按照定义的顺序；
+2. 接着执行 `action` 定义的块；
+3. 然后执行 `after` 钩子，按照定义的顺序；
+4. 最后执行 `around` 钩子的后半部分，按照定义的**逆序**执行。
+
+举例（以下按照 `1`、`2`、`3` 的数字顺序执行）：
 
 ```ruby
 class DemoApp < Meta::Application
   namespace '/foo' do
-    apply Foo
+    before { puts 1 }
+    around { |next_action|
+       puts 2
+       next_action.execute(self)
+       puts 9
+    }
+    around { |next_action|
+       puts 3
+       next_action.execute(self)
+       puts 8
+    }
+    before { puts 4 }
+    after { puts 6 }
+    after { puts 7 }
+
+    get '/request' do
+      puts 5
+    end
   end
 end
 ```
 
-模块应用最常用的场景是将接口分离到单独的文件中定义。这里我贴出我在一个实际项目中的模块划分：
+#### 使用钩子的注意事项
+
+请注意，钩子的执行顺序是严格按照以上顺序执行的，与你定义的顺序无关。请确保 `before` 和 `around` 钩子优先于 `after` 的顺序定义，因为它们的执行也是优先于 `after` 的。
+
+另外，钩子的执行不会覆盖参数解析和返回值渲染，亦即 `before` 钩子在参数解析之后执行，`after` 钩子在返回值渲染之前执行，而 `around` 钩子亦不会覆盖参数解析和返回值渲染。
+
+钩子不会中断执行。如果要在钩子中中断程序的执行，可使用 `abort_execution!` 方法：
 
 ```ruby
-class OpenAPIApp < Meta::Application
-  apply API::Logins
-  apply API::Users
-  apply API::Organizations
-  apply API::Projects
-  apply API::Versions
-  apply API::Members
+before do
+  token = request.get_header('HTTP_X_TOKEN')
+  // ... parse token
+rescue TokenInvalidError => e
+  response.status = 401
+  response.message = "Token 格式异常：#{e.message}"
+  abort_execution!
 end
 ```
 
-## 路由内部定义
+`abort_execution!` 同时会跳过返回值渲染的执行。
 
-现在我们关注路由内部细节的定义，包括标题、描述、参数、返回值乃至于如何实现业务逻辑等。我们知道，路由是通过 `route` 方法（以及它的一系列便捷方法 `get`、`post` 等），也就是说我们现在开始关注 `route` 方法内部能定义什么。
+冷知识：`Meta::Application` 本身也可视为一个命名空间定义，`namespace` 内能用到的方法也可以在 `Meta::Application` 内使用。
 
-本来想大书特书，结果发现以下代码示例便能将用到的宏命令列举完毕。
+### 异常拦截
+
+在 `namespace` 中可使用 `rescue_error` 拦截异常。
 
 ```ruby
-route '/user', :put do
-  title '更新用户'
-  description '接口的详细描述'
-  tags ['User'] # 传递一个数组
-  params do
-    # 定义参数
-    param :user do
-      param :name
-      param :age
+class DemoApp < Meta::Application
+  namespace '/users/:id' do
+    rescue_error ActiveRecord::RecordNotFound do |e|
+      response.status = 404
+      response.body = ["所访问的资源不存在"]
     end
-  end
-  status 200 do
-    # 定义返回值，其中 200 是状态码
-    expose :user do
-      expose :name
-      expose :age
+    
+    get do
+      action do
+        user = User.find(params[:id])
+      end
     end
   end
-  action do
-    # 业务逻辑在这里实现，通过 params 方法访问参数，render 方法渲染实体
-    user = get_user
-    user.update!(params[:user])
-    render :user, user
-  end
 end
 ```
 
-### `meta` 命令
+以下是 Meta 框架抛出的异常：
+
+- `Meta::Errors::NoMatchingRoute`：路由不匹配时。
+- `Meta::Errors::ParameterInvalid`：参数存在异常时。
+- `Meta::Errors::RenderingInvalid`：响应值存在异常时。
+- `Meta::Errors::UnsupportedContentType`：框架只支持 `application/json` 的参数格式。当客户端的请求体不是这个格式时，会抛出这个错误。
 
-除 `action` 之外，`route` 块下其余的命令都与文档的生成相关。它们都可以被汇总到一个称为 `meta` 的块内：
+#### 嵌套命名空间下的异常拦截
+
+拦截异常先在子作用域下拦截；如果拦截失败则继续在父作用域下拦截。下面的例子中：
 
 ```ruby
-route '/user', :put do
-  meta do
-    title '更新用户'
-    description '接口的详细描述'
-    tags ['User'] # 传递一个数组
-    params do
-      # 定义参数
+class DemoApp < Meta::Application
+  namespace '/foo' do
+    rescue_error ErrorOne do
+      puts "rescued in /foo" #（1）
     end
-    status 200 do
-      # 定义返回值
+
+    rescue_error ErrorTwo do
+      puts "rescued in /foo" #（2）
+    end
+
+    namespace '/bar' do
+      rescue_error ErrorOne do
+        puts "rescued in /foo/bar" #（3）
+      end
+      
+      get do
+        action do
+        	raise ErrorOne
+      	end
+      end
+      
+      put do
+        action do
+        	raise ErrorTwo
+      	end
+      end
     end
   end
-  action do
-    # 业务逻辑仍在这里实现
+end
+```
+
+调用 `GET /foo/bar` 请求时会在（3）处被捕获；调用 `PUT /foo/bar` 请求时会在（2）处被捕获。
+
+#### `Meta::Errors::NoMatchingRoute` 只能在顶层被捕获
+
+由于框架实现的特殊性，异常 `Meta::Errors::NoMatchingRoute` 只会在顶层抛出。因此，只有在 `namespace` 的顶层捕获才有效果。
+
+```ruby
+class DemoApp < Meta::Application
+  # 在此捕获有效
+  rescue_error Meta::Errors::NoMatchingRoute do |e|
+    response.status = 404
+    response.body = ["404 Not Found"]
+  end
+
+  namespace '/foo' do
+    # 在此捕获无效
+    rescue_error Meta::Errors::NoMatchingRoute do |e|
+      response.status = 404
+      response.body = ["404 Not Found"]
+    end
   end
 end
 ```
 
-### `namespace` 下的 `meta` 命令
+即使是上面的例子，调用 `GET /foo/bar` 请求时也只有顶层的异常拦截起了作用。
 
-`namespace` 下可以也定义 `meta` 块，它可以定义接口声明的公共部分，应用到它的子路由下：
+### `namespace` 的 `meta` 宏
+
+同 `route` 宏内，`namespace` 宏内部可以定义 `meta` 宏。`namespace` 定义的 `meta` 宏定义下属路由的公共部分，其会应用到全部子路由，除非在 `route` 宏内复写。
 
 ```ruby
-namespace '/user/:id' do
+namespace '/users/:id' do
+  # 以下 meta 内定义的部分会应用到 GET /users/:id 和 PUT /users/:id 两个路由。
+  # 其中，因为 title 两个路由有重写，因此会使用两个路由自己的 title 定义。
+  # description 两个路由都没有独自定义，因此会统一使用 meta 中的定义。
+  # tags 同理，它们都挂载在同一个 Tag 下。
+  # params 定义比较特殊，子路由下的定义不是复写而是补充。因此 GET /users/:id 包含一个参数 id，PUT /users/:id 包含了两个参数
+  # id 和 user.
+  # status 与 params 同理，但由于子路由内没有 status 定义，从而它们两个都是使用 meta 中的定义，即返回一个 user 属性。
   meta do
-    # 在 namespace 下定义 title 和 description 没有意义
+    title '处理用户详情'
+    description '通过路径参数获取用户数据，并对用户数据做一定的处理，比如查看、更新'
     tags ['User'] # 该 namespace 下的接口归到 User 标签下
     params do # 定义共同参数
       param :id
@@ -374,6 +517,206 @@ namespace '/user/:id' do
 end
 ```
 
+## 路由的执行环境 （`Meta::Execution`）
+
+当路由在执行过程中，会将块绑定到一个 `Meta::Execution` 实例中执行。`before`、`after` 等钩子，`action` 定义的块内，以及异常拦截的过程中，其执行环境都会绑定到当前的  `Meta::Execution` 实例。
+
+```ruby
+class DemoApp < Meta::Application
+  before do
+    @current_user = "Jim" # 设置一个环境变量
+  end
+  
+  rescue_error StandardError do
+    p @current_user # 可以访问先前设置的实例变量
+  end
+  
+  get '/user' do
+    action do
+      p @current_user # 可以访问先前设置的实例变量
+      raise # 抛出异常
+    end
+  end
+end
+```
+
+### `Meta::Execution` 提供的方法。
+
+#### `#request`
+
+`request` 方法返回 [`Rack::Request`](https://www.rubydoc.info/gems/rack/Rack/Request) 实例，它是 Rack 框架提供的包装类，用于简化 HTTP 操作。
+
+#### `#response`
+
+`response` 方法返回 [`Rack::Response`](https://www.rubydoc.info/gems/rack/Rack/Response) 的实例，它是 Rack 框架的包装类，用于简化 HTTP 操作。
+
+#### `#params`
+
+不要与 `.params` 宏所混淆，它是 `Meta::Execution` 提供的实例方法，返回解析后的参数。参数的解析参考 `params` 宏的定义。
+
+#### `#render`
+
+定义实际响应体时使用 `render` 方法。`render` 方法参考 `status` 定义的响应体格式过滤和验证字段。
+
+#### `#abort_execution!`
+
+中断后续的执行。如果是在 `before` 块中执行这个方法，则跳过后续的 `before`、`action` 和 `after` 块；如果是在 `action` 块中执行这个方法，则跳过 `after` 块。注意，这个方法会跳过响应体渲染阶段。
+
+### 共享模块
+
+不要在 `Meta::Application` 内部定义方法，在它内部直接定义的方法应用到 `Meta::Execution` 实例。如果需要在当前以及后续路由用到公共的方法，可以在 `shared` 块内定义：
+
+```ruby
+class DemoApp < Meta::Application
+  shared do
+    def current_user
+      @current_user
+    end
+  end
+  
+  before do
+    @current_user = "Jim" # 设置一个环境变量
+  end
+  
+  get '/user' do
+    action do
+      p current_user # 在路由内访问方法
+    end
+  end
+  
+  namespace '/foo' do
+    get '/user' do
+      action do
+        p current_user # 在子命名空间内也能访问到方法
+      end
+    end
+  end
+end
+```
+
+除此之外，`shared` 的参数也接受模块。
+
+```ruby
+module HelperFoo
+  def foo; 'foo' end
+end
+
+module HelperBar
+  def bar; 'bar' end
+end
+
+class DemoApp < Meta::Application
+  shared HelperFoo, HelperBar
+  
+  get '/user' do
+    action do
+      p foo
+      p bar # 可访问模块定义的方法
+    end
+  end
+end
+```
+
+## 模块（`Meta::Application`）
+
+### `Meta::Application` 等同于 `namespace` 定义
+
+要知道 `Meta::Application`，第一个事情就是它等同于 `namespace` 定义。像 `namespace` 一样，能定义路由、钩子、异常拦截的地方都可以在 `Meta::Application` 内直接定义。
+
+```ruby
+class DemoApp < Meta::Application
+  # meta 定义，能应用到下属子路由的所有地方
+  meta do
+    # ...
+  end
+  
+  # 它将捕获下属子路由的所有异常
+  rescue_error Exception do
+    # ...
+  end
+  
+  # 钩子，最先执行
+  before do
+    # ...
+  end
+  
+  # 钩子，最后执行
+  after do
+    # ...
+  end
+
+  # 定义嵌套命名空间
+  namespace '/...' do
+    # ...
+  end
+  
+  # 也可以直接定义路由
+  route '/...', :post do
+    # ...
+  end
+end
+```
+
+你可以将 `Meta::Application ` 视为路径定义为 `/` 的命名空间。
+
+### `Meta::Application` 是可复用的模块
+
+遇到大型项目时，将 API 定义分离成若干个单独的文件更好的组织。做到这一点，就用到 `namespace` 中提供的 `apply` 方法。
+
+继承自 `Meta::Application` 的类都是一个模块，它可以在 `namespace` 中被复用。
+
+```ruby
+class Foo < Meta::Application
+  route '/foo' do
+    # ...
+  end
+end
+
+class DemoApp < Meta::Application
+  apply Foo
+end
+```
+
+将定义写在一个类里，其等价于：
+
+```ruby
+class DemoApp < Meta::Application
+  route '/foo' do
+    # ...
+  end
+end
+```
+
+`apply` 方法还可跟一个参数 `tags: [...]`，统一覆盖被引入的模块在渲染文档时声明的 `tags`：
+
+```ruby
+class OpenAPIApp < Meta::Application
+  apply API::Logins, tags: ['Login']
+  apply API::Users, tags: ['User']
+  apply API::Organizations, tags: ['Organization']
+  apply API::Projects, tags: ['Project']
+  apply API::Versions, tags: ['Version']
+  apply API::Members, tags: ['Member']
+end
+```
+
+### `Meta::Application` 是一个 Rack 应用
+
+`Meta::Application` 同时也是一个 Rack 应用，将它挂载在 Rack 下可以直接作为一个服务运行。我们看一个最简单的 `Meta::Application` 实例：
+
+```ruby
+class DemoApp < Meta::Application
+  route '/', :get do
+    title '应用的根路径'
+    action do
+      response.body = ["Hello, world!"]
+    end
+  end
+end
+```
+
+> 将它挂载在 Rack 下并访问 `http://localhost:9292` 你将看到接口返回 `"Hello, world"` 文本。
+
 ## 参数定义
 
 本节介绍参数和返回值如何定义。因为 Meta 框架在底层不区分参数和返回值，它们都统一为“实体”的概念。因此，当涉及到语法细节时，在参数、返回值、实体内都是一致的。

data/lib/meta/application/execution.rb

@@ -100,22 +100,36 @@ module Meta
         end
 
         new_hash = entity_schema.filter(hash, **options, execution: self, stage: :render, validation: ::Meta.config.render_validation, type_conversion: ::Meta.config.render_type_conversion)
+        response.content_type = 'application/json' if response.content_type.nil?
         response.body = [JSON.generate(new_hash)]
       else
         # 渲染多键值结点
-        new_hash = renders.map do |key, render_content|
+        errors = {}
+        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)
-
-          filtered = schema.filter(render_content[:value], **render_content[:options], execution: self, stage: :render)
-          [key, filtered]
+          final_value[key] = schema.filter(render_content[:value], **render_content[:options], execution: self, stage: :render)
+        rescue JsonSchema::ValidationErrors => e
+          # 错误信息再度绑定 key
+          errors.merge! e.errors.transform_keys! { |k| k.empty? ? key : "#{key}.#{k}" }
         end.to_h
-        response.body = [JSON.generate(new_hash)]
+
+        if errors.empty?
+          response.content_type = 'application/json' if response.content_type.nil?
+          response.body = [JSON.generate(final_value)]
+        else
+          raise Errors::RenderingInvalid.new(errors)
+        end
       end
     rescue JsonSchema::ValidationErrors => e
       raise Errors::RenderingInvalid.new(e.errors)
     end
 
+    def abort_execution!
+      raise Abort
+    end
+
     private
 
     def parse_raw_params
@@ -134,22 +148,18 @@ module Meta
     end
 
     def parse_request_body_for_replacing
-      begin
-        request_body_schema.filter(params(:raw), stage: :param)
-      rescue JsonSchema::ValidationErrors => e
-        raise Errors::ParameterInvalid.new(e.errors)
-      end
+      request_body_schema.filter(params(:raw), stage: :param)
+    rescue JsonSchema::ValidationErrors => e
+      raise Errors::ParameterInvalid.new(e.errors)
     end
 
     def parse_request_body_for_updating
-      begin
-        request_body_schema.filter(params(:raw), stage: :param, discard_missing: true)
-      rescue JsonSchema::ValidationErrors => e
-        raise Errors::ParameterInvalid.new(e.errors)
-      end
+      request_body_schema.filter(params(:raw), stage: :param, discard_missing: true)
+    rescue JsonSchema::ValidationErrors => e
+      raise Errors::ParameterInvalid.new(e.errors)
     end
 
-    class Abort < StandardError
+    class Abort < Exception
     end
 
     # 使得能够处理 Execution 的类作为 Rack 中间件
@@ -162,7 +172,6 @@ module Meta
         execute(execution, request.path)
 
         response = execution.response
-        response.content_type = 'application/json' unless response.no_content?
         response.to_a
       end
     end

data/lib/meta/application/parameters.rb

@@ -11,15 +11,23 @@ module Meta
     end
 
     def filter(request)
-      parameters.map do |name, options|
+      errors = {}
+      final_value = {}
+
+      parameters.each do |name, options|
         schema = options[:schema]
         value = if options[:in] == 'header'
-          schema.filter(request.get_header('HTTP_' + name.to_s.upcase.gsub('-', '_')))
-        else
-          schema.filter(request.params[name.to_s])
-        end
-        [name, value]
-      end.to_h
+                  schema.filter(request.get_header('HTTP_' + name.to_s.upcase.gsub('-', '_')))
+                else
+                  schema.filter(request.params[name.to_s])
+                end
+        final_value[name] = value
+      rescue JsonSchema::ValidationError => e
+        errors[name] = e.message
+      end
+      raise Errors::ParameterInvalid.new(errors) unless errors.empty?
+
+      final_value
     end
 
     def to_swagger_doc

data/lib/meta/application/route.rb

@@ -20,16 +20,14 @@ module Meta
     def execute(execution, remaining_path)
       path_matching.merge_path_params(remaining_path, execution.request)
 
-      begin
-        execution.parse_parameters(@meta[:parameters]) if @meta[:parameters]
-        execution.parse_request_body(@meta[:request_body]) if @meta[:request_body]
+      execution.parse_parameters(@meta[:parameters]) if @meta[:parameters]
+      execution.parse_request_body(@meta[:request_body]) if @meta[:request_body]
 
-        action.execute(execution) if action
+      action.execute(execution) if action
 
-        render_entity(execution) if @meta[:responses]
-      rescue Execution::Abort
-        execution
-      end
+      render_entity(execution) if @meta[:responses]
+    rescue Execution::Abort
+      nil
     end
 
     def match?(execution, remaining_path)

data/lib/meta/errors.rb

@@ -13,7 +13,7 @@ module Meta
     end
 
     class RenderingInvalid < JsonSchema::ValidationErrors
-      def initialize(errors)
+      def initialize(errors = {})
         super(errors, "渲染实体异常：#{errors}")
       end
     end

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

@@ -34,7 +34,7 @@ module Meta
         private
 
         def apply_array_schema?(options, block)
-          options[:type] == 'array' && (options[:items] || options[:ref] || options[:dynamic_ref] || block)
+          options[:type] == 'array'
         end
 
         def apply_object_schema?(options, block)

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

@@ -23,6 +23,8 @@ module Meta
 
       def initialize(options = {})
         options = OPTIONS_CHECKER.check(options)
+        raise '不允许 BaseSchema 直接接受 array 类型，必须通过继承使用 ArraySchema' if options[:type] == 'array' && self.class == BaseSchema
+
         @options = SchemaOptions.normalize(options)
       end
 

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

@@ -96,9 +96,9 @@ module Meta
       @object_converters = {
         [Object] => lambda do |value|
           if [TrueClass, FalseClass, Integer, Float, String].any? { |ruby_type| value.is_a?(ruby_type) }
-            raise TypeConvertError, I18n.t(:'json_schema.errors.type_convert.object', value: value, real_type: I18n.t(:'json_schema.type_description.basic'))
+            raise TypeConvertError, I18n.t(:'json_schema.errors.type_convert.object', value: value, real_type: I18n.t(:'json_schema.type_names.basic'))
           elsif value.is_a?(Array)
-            raise TypeConvertError, I18n.t(:'json_schema.errors.type_convert.object', value: value, real_type: I18n.t(:'json_schema.type_description.array'))
+            raise TypeConvertError, I18n.t(:'json_schema.errors.type_convert.object', value: value, real_type: I18n.t(:'json_schema.type_names.array'))
           end
 
           ObjectWrapper.new(value)

data/meta-api.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |spec|
   spec.name          = "meta-api"
-  spec.version       = "0.0.5"
+  spec.version       = "0.0.6"
   spec.authors       = ["yetrun"]
   spec.email         = ["yetrun@foxmail.com"]
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: meta-api
 version: !ruby/object:Gem::Version
-  version: 0.0.5
+  version: 0.0.6
 platform: ruby
 authors:
 - yetrun
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-04-27 00:00:00.000000000 Z
+date: 2023-05-26 00:00:00.000000000 Z
 dependencies: []
 description: 一个 Web API 框架，该框架采用定义元信息的方式编写 API，并同步生成 API 文档
 email:
@@ -130,7 +130,7 @@ metadata:
   allowed_push_host: https://rubygems.org
   homepage_uri: https://github.com/yetrun/web-frame
   source_code_uri: https://github.com/yetrun/web-frame.git
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -145,8 +145,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.7
-signing_key: 
+rubygems_version: 3.3.26
+signing_key:
 specification_version: 4
 summary: 一个 Web API 框架
 test_files: []