yetrun (Yet Run)

Rails 中实现自定义卡片视图帮助方法的心路历程

yetrun — Fri, 26 Jul 2024 11:12:00 +0800

实现一个基本的 `cards_for` 效果

我需要用 BootStrap Card 组件实现一个卡片列表，单个的 BootStrap Card 组件的使用方式如下：

<div class="card" style="width: 18rem;">
  <div class="card-body">
    <h5 class="card-title">Card title</h5>
    <p class="card-text">Some quick example text to build on the card title and make up the bulk of the card's content.</p>
    <a href="#" class="btn btn-primary">Go somewhere</a>
  </div>
</div>

这是它的效果：

现在我需要展示一堆这样的卡片，卡片之间要有间距，大致是这样的效果（这是一行的效果，实际上应当支持多行，这里不再展示）：

就此机会，我的第一步是实现一个名为 card 的局部视图，像这样：

<!-- _card.html.erb -->
<div class="card" style="width: 18rem;">
  <div class="card-body">
    <h5 class="card-title"><%= name %></h5>
    <p class="card-text"><%= description %></p>
    <a href="<%= link %>" class="btn btn-primary">Go somewhere</a>
  </div>
</div>

card 局部视图接受三个变量：name、description、link，分别显示卡片的标题，正文和指向的链接。

如果需要显示一堆卡片，我需要这样做：

<div class="d-flex gap-3 p-3 flex-wrap">
  <% @models.each do |model| %>
    <%= render "card", name: model.name, 
                       description: model.description, 
                       link: model.link %>
  <% end %>
</div>

然后我想到我的项目中有一堆这样模型，它也是满足 name、description、link 这三个属性的。为了减少重复代码，我决定实现一个自定义的 helper 方法，来简化这些卡片列表的渲染过程。这不仅能提高代码的可读性，还能确保一致的样式和结构。

我将这个方法命名为 cards_for，就像 Rails 自带的视图帮助方法 form_for 等一样，cards_for方法只接受一个满足要求的 models 属性即可：

<%= cards_for models: @models %>

在 Helper 中我只需要实现成这样：

module CardsHelper
  def cards_for(models:)
    cards_html = models.map do |model|
      render "card", name: model.name, 
                     description: model.description, 
                     link: model.link    
    end.join.html_safe
    content_tag :div, cards_html, class: "d-flex gap-3 p-3 flex-wrap"
  end
end

在 Helper 中写代码，简直就像在视图中写代码那样，只要你找到对应的方法。

为 `cards_for` 添砖加瓦所受的伤

接下来，我的任务是继续为 cards_for 方法添砖加瓦。因为我们总不能保证传递进来的模型满足 name、description、link 这样的命名关系，为了适应这种情况，我的初步想法是，为 cards_for 方法添加一个块，将块的返回值作为局部变量传递给 card 视图：

module CardsHelper
  def cards_for(models:, &block)
    cards_html = models.map do |model|
      if block_given?
        options = block.call(model)
      else
        options = {
          name: model.name, 
          description: model.description, 
          link: model.link
        }
      end

      render partial: "card", locals: options # 保险起见，我写成这样
    end.join.html_safe
    content_tag :div, cards_html, class: "d-flex gap-3 p-3 flex-wrap"
  end
end

然后我们就可以针对模型显示一些不一样的东西，例如：

<%= cards_for models: @models do |model| %>
  {
    name: "T-" + model.name,
    description: "T-" + model.description,
    link: "https://www.sina.com"
  }
<%  end %>

然后给我报了这样一个错误：

undefined method `keys' for "\n  {\n    name: \"T-\" + model.name,\n    description: \"T-\" + model.description,\n    link: \"https://www.sina.com\"\n  }\n":String

原因是我调用的写法写错了，要改成这样才正确：

<%= cards_for models: @models do |model|
  {
    name: "T-" + model.name,
    description: "T-" + model.description,
    link: "https://www.sina.com"
  }
end %>

注意区别很有限，只比上一个少了一个 %> 结束标签和 <% 打开标签，但也是我们经常犯的错误。原因是因为 ERB 对于不在 <% ... %> 标签内的代码，它会视为纯文本。请细细品味，方能知晓。

至此，一个 cards_for 帮助方法已经实现了。还可以继续为其添砖加瓦，利用 Ruby 语言的灵活性。

meta-api: 版本 0.2.0 小结

yetrun — Fri, 28 Jun 2024 11:04:40 +0800

项目地址：https://github.com/yetrun/web-frame

meta-api 已经拼拼凑凑地到了 0.2.0 版本了，这次的更新算是又一次的升华和梳理。可以说 meta-api 是我对于 API 开发的所有经验总结，也是我对于 API 开发的所有期望。只不过 API 开发是一个见仁见智的水平，所以 meta-api 也一直处于不温不火的状态。

编写框架是个非常劳累的活计，基本属于吃力不讨好吧。支撑我干下去的初衷只是对我当初的想法的坚持，我想让它实现，看看效果。这次 0.2.0 版本有可能是最终形态的雏形了，以后只做一些小修小补的工作，实在是力不从心了。

meta-api 它有两大特点：

它的核心思想是：设计即是实现。这样，我们就可以避免实现与文档不一致的问题。
它提供了静态场景化的方式，用于定义不同的场景。这样，我们就可以在不同的接口中声明不同的场景。更为要紧的事，这样的声明体现在文档中，不会出错，不会造成歧义。

主要的核心问题：设计即是实现

在 API 开发领域，我所遇到的一个主要问题是，要写两茬罪：1. 实现一套 API；2. 针对实现的 API 编写文档给前端看（或者反过来）。总之，遇到一些修改的时候，比如一个接口多返回一个字段，我们总要去改两个地方。如果忘记修改（这往往会出现），就会遇到实现与文档不一致的地方，徒增交流成本。

meta-api 的核心思想是：设计即是实现。也就是说，我们只需要设计一次，然后就可以直接生成实现和文档。这样，我们就可以避免实现与文档不一致的问题。

Ruby Grape 框架

Grape 框架是 Ruby 语言里专注于 API 开发的，它其实可以生成对应的文档。我在 2022 年的时候逐渐放弃它，主要是它做到了“设计即实现”，但又好像只做到了一半。所以，我就想自己写一个。

首先，它支持参数定义，然后使用 grape-entity 可以渲染实体给前端。但是它的参数定义和实体渲染是分开的，这造成了前面提到的两茬罪最终还是两茬罪，只不过添加字段的点变了。

在我写稿的日子里，Grape 框架似乎有所升级，支持通过实体的 .documentation 方法生成字段用于 params 宏，我是从官方文档的前面小节里看到的：

class BasicAPI < Grape::API
  desc 'Statuses index' do
    params (configuration[:entity] || API::Entities::Status).documentation
  end
  params do
    requires :all, using: (configuration[:entity] || API::Entities::Status).documentation
  end
  get '/statuses' do
    statuses = Status.all
    type = current_user.admin? ? :full : :default
    present statuses, with: (configuration[:entity] || API::Entities::Status), type: type
  end
end

这里有很多别扭的点，不知道你发现没发现。

这个功能在我 2022 年的时候就已经有了，那时非常地不好用。实体里面的 type 格式与 params 宏里的不一样，另外还不支持嵌套。不知现在这些问题解决了没。我想总归是解决了，否则不会就此放出来。（关于这一点，希望懂行的朋友能给个指正）

那么对比一下，如果用 meta-api 如何实现呢？是不是会更好：

class BasicAPI < MetaAPI::API
  get '/statuses' do
    title 'Statuses index'
    params API::Entities::Status
    status 200, API::Entities::Status
    action do
      statuses = Status.all
      scope = current_user.admin? ? ['full'] : []
      render statuses, scope: scope
    end
  end
end

不是有意要比较的意思，但总归消除别扭的。比如 Grape 写法里那个奇怪的 requires :all 参数。而且正因为如此，它要多写一句 desc 宏在里面声明 params 的正确文档。

Grape 是把它的所有的优秀才华都放在参数的定义上面了，而将实体渲染的部分留给第三方插件去完成。归根结底，它还是将自己看作一个 API 实现框架，而不是一个 API 设计框架。

但是，如果仅仅说实现，Rails API 又哪里有问题呢？

Rails API

在更早期的时候，我一直用的是 Rails API only. Rails API 能够集成 Rails 所能提供的几乎所有组件，这是它的最大优势。它唯一的缺点就是没有文档。当然，你可以通过插件生成文档，但这依然是两茬罪的事情。

其实用 Rails API 挺自由的。如果不考虑文档的约束，只管实现的话，任何框架都挺自由的，Rails API 更甚。但是，我的理念是，开发 API 就得提供文档。不提供只是太麻烦了而已。但如果生成文档不麻烦了呢？比如 meta-api.

使用 Rails API 时，一定要理解 MVC 思想。很多人会觉得 Rails API 没有参数验证，没有实体渲染。其实它是有的，你要按照框架的思维去思考。比如，参数验证，你可以在 model 里面定义。实体渲染，你要用到 JBuilder.

就拿一个登录接口为例，它接受参数 email 和 password，返回 token：

class SessionsController < ApplicationController
  def create
    login = Login.new(login_params)
    @token = login.login
  end
end

class Login < ActiveModel
  include ActiveModel::API

  attr_accessor :email, :password

  validates :email, presence: true
  validates :password, presence: true

  def login
    return nil unless valid?
    User.find_by(email: email).authenticate(password)
  end
end

# JBuilder
json.token @token

就好像 ActiveRecord 一样，你可以在 ActiveModel 里面做各种验证。而编程式的 JBuilder 渲染，就像 erb 一样灵活。

只不过是没有文档而已，如果只是自产自销的项目，没有文档无可厚非（只不过这个时候，你用 Rails 全栈似乎是更好的选择，彻底避免了两茬罪的问题）。

meta-api

meta-api 的核心思想是：设计即实现。截止如今 0.2.0 版本，我估摸着实现了 80% 以上了吧。它也从根本上解决了两茬罪的问题，因为参数和返回值里用到的实体是相通的。也就是说，如何定义参数的，你也就用同样的方法定义返回值的字段。

有关 meta-api 的文档，主要看两个：

教程

字段场景化

静态场景化

meta-api 与其他的框架最不同的地方：静态场景化。因为最考虑文档的优先性，因此才会有这种考虑，用静态的语法声明字段的场景，这样才最可能生成对应的文档。

场景是个通用的说法。这其中包括哪些字段用于参数，哪些字段用于返回值；哪些字段用于这个接口，哪些字段用于这个接口。meta-api 提供了静态声明这类场景的方式，这也就意味着这些差异文档中可以体现出来。

一个接口，不应该接受一个实体的所有字段，同样也不应该返回所有字段。这是为了安全性。以 User 字段为例：

class UserEntity < Meta::Entity
  property :id
  property :name
  property :email
  property :password
  property :profile
end

在这里，id 字段不应该作为参数，主键不能被修改；password 字段不应该返回，密码不能被泄露。

更复杂的情况下，针对不同的接口应返回不同的字段。profile 字段，只有当 /users/:id 这样的详情类的接口才返回，而不应该在 /users 这样的列表类的接口返回。

meta-api 提供了 scope 方法，用于定义不同的场景。这样，我们就可以在不同的接口中声明不同的场景。更为要紧的事，这样的声明体现在文档中，不会出错，不会造成歧义。

class UserEntity < Meta::Entity
  params do
    param :id
    # 可以在这里定义更多的参数字段
  end

  # 仅用于参数
  render do
    expose :password
    # 可以在这里定义更多的返回字段
  end

  property :name
  # 可以在这里定义更多的基本字段，这些字段在任何情况下都会用到

  scope Detail do
    property :profile
    # 可以在这里定义更多的 Detail 场景字段
  end

  scope Admin do
    property :email
    # 可以在这里定义更多的 Admin 场景字段
  end
end

我写了这么一个文档：字段场景化，这里面举出了常用的场景示例。这里仅给出一个小小的窥探吧。

最后想说的话

我真心感受到一点，国内的短平快开发环境下大多数开发者不认真去做文档。文档这玩意，有就行，有时候语义和实现不一致也懒得改，反正微信聊天记录有。这种情况下，meta-api 似乎有点多余。它所提供的自动一致性文档功能，也并被大家所认可。

然后，国内的 Ruby 论坛本身也快变成了招聘和瞎扯淡的地方，技术交流的地方越来越少。

只不过，用过的人应该会感受到，meta-api 的确是一个好东西。它的设计思想是对的，只不过它的实现方式目前可能不对，但没有反馈我也不清楚。只不过，它的应用场景太小了，太小了。就像双拼输入法的感觉那样，没用之前不知所云，用了之后真是舒服。

meta-api: 让后端开发者不用再写文档

yetrun — Sat, 05 Aug 2023 17:04:09 +0800

meta-api 框架历经长时间的迭代，终于在今天发布了第一个稳定的版本 0.1 版了。借此机会，我再次向 Ruby 社区发表下这个项目，如有打扰之处还请见谅。这次的文章比较长，不知道 Ruby China 论坛支不支持发表长文章，会不会产生字数限制导致截断的情况。也许长文章会劝退某些 Ruby 伙伴，没事那就跳着看到最后吧。这次我将介绍下我对后端 API 开发的看法，介绍 meta-api 框架文档化支持的能力和它的与众不同之处。这次我还将它与 Rails、Grape 框架做个简单的比较。当然，欢迎大家来交流，我在文末列出交流的途径，希望能与有志同道合的同志一起讨论，当然更希望大家一起参与建设。

背景简介

现在前后端分离已经成为了 Web 项目开发的主要模式。一个项目组内分为前端开发人员和后端开发人员，后端开发者负责产出 Restful 接口，前端开发者通过调用接口获取数据或操作。在前后端交流接口的过程中，在写 API 文档上，后端开发者一般持有三种态度：

不想写文档，压根不打算产出 API 文档；
愿意写文档，但产出的文档很粗糙，经常跟接口的实现对不上；
很细致地写文档，产出的文档也很好，但写文档的过程非常地繁琐，也有少部分与接口的实现对不上的情况发生。

我没有完全调研大家编写文档的方式，据我所知有单独写一个 Markdown 文件的，有用 ApiFox 之类可视化工具的，有用代码注释或注解产生 API 文档的，不一一列举了。但这些工具都有一个共同点：分心。程序员在百忙之中不得不抽出相当一部份时间专门处理文档的事情，让自己的工作在写文档和写代码之间不断地跳跃。

除了写文档的繁琐之外，国内开发者对待文档的浮躁也是一个方面。项目组内往往是铺天盖地的讨论声，前端一会儿问问后端这个接口怎么用，那个接口怎么会报错？后端也乐于解答这些问题。他们在开发中往往不去参考文档。有些项目组可能会生产文档，但是如果文档的表达能力不够好，开发过程中经常地弃之不用，那么即使产出了文档也起不到一丁点作用。

项目组到底需不需要写文档呢？如果你的回答是不需要，那也许你找到了适合你们项目组开发的最佳途径。但总体上，生产 API 文档至少有几个好处：

减少前后端联调和沟通的成本，当然前提是文档的质量要足够好。
从 API 文档了解项目的设计结构，文档可作为项目组沟通的媒介。
如果你开发的是一个开放 API 项目，API 文档不可或缺。

我一直在想，让人们讨论要不要产出文档这个话题，是不是因为生产文档的额外工作让人厌烦。所以，如果文档的工作足够简单，成为了开发代码自然产生的附属品，那么纠结它重不重要的话题还有意义吗？

meta-api 工具简介

这篇文章阐述了一个想法，介绍了一种工具，或者是一个框架，目的是为了让后端开发者简化写文档的工作。甚至达到一个终点，后端开发者不用再写文档了，因为文档就在那里，就在你的代码里。

这里介绍的一个新的框架，是我历时一年半左右的大大小小的时间里积累而完成的。现在我认为它可以达到发布一个较为稳定的版本时机了，至少从实践上我探索出了代码同步文档的可行性。总结起来，它最大的特点是：

写代码时同步产生文档（结合配套的 OpenAPI 工具基本达到实时的效果），开发者不用再单独考虑文档的生成问题；
文档与接口的逻辑是一致的，包括文档中定义了几个字段，接口就接受几个字段，不多也不少；
只需要在一个地方定义实体，就可以到处使用，包括参数中、返回中、列表接口、详情接口，其中提供了一个简单的机制在以上不同的场景下产生不同的字段。

写代码时同步产出文档

我录了一个视频，我在左边写代码，等我把代码写完之后，右边就实时出现更新后的文档了：

发布后发现 Ruby China 不能直接显示视频，大家伙可以点击下面的链接访问视频：

同步生成文档

左边是一个 Vim 编辑器，右边同步产生文档。当我们在代码中将接口的语义用各种宏命令定义好后，保存文件，右边的 API 文档预览同步生成更新后的效果。所以，你完全可以一边写代码一边检查文档；或者当你写完代码后统一检查文档，哪里需要调整的再回过头去调整即可。

文档与接口的逻辑是一致的

其实当你看到视频的最后，再截一张图时，就可以发现端倪了。编辑器里的代码，都能对应上 OpenAPI 文档里的一部份。甚至是字段都能对应上。仔细看右边的文档，同样引用的 ArticleEntity 这个实体，但在文档显示时却能正确地说明参数包括 title、content 字段，渲染返回时包括 id、 title、content 三个字段。

一处编写，到处使用

还是这个例子，你通篇看到对 ArticleEntity 的引用。其实，对于文章这个实体的参数和响应值，我就写在了这一个类里，然后就几乎用在所有的地方，包括参数、返回值，也包括列表接口、详情接口。所谓一处编写，到处使用，你将享受到统一管理的便利。

框架与 Rails 和 Grape 的比较

首先，meta-api 是纯 API 框架，接受 JSON 参数，生产 JSON 实体；Rails 是全栈框架。它们的应用场景不一样。全栈开发（也就是通常所说的一个人单撸整个项目），适合用 Rails 开发，中间没必要生产 API 文档。前后端分离的开发，中间需要生产 API 文档，适合 meta-api 开发。

Rails 有纯 API 模式，但仍是全栈的思维（MVC），我个人认为开发起来还是有诸多不便。而且，它不能生产文档。通过 rswag 生产的文档，没有一致性可言。你完全可以在文档中写是一套，在实际逻辑中运行时又是一套。

Grape 是纯 API 框架，也能生产 Swagger 文档。但它不是面向文档优先的框架，一致性做得不足。它在参数方面的文档一致性做得很好，但在渲染方面却欠佳。而且，它无法做到一处编写到处使用，参数定义和返回值定义用了两套不同的语法。

meta-api 框架天生地就是面向文档优先的，所以目前来说，一致性方面做得最足。这是它与其他框架目前的最大区别。如果你是 Rails 全栈开发者，暂时用不到 meta-api，保持原有技术栈就好。如果你是 Grape 框架使用者，我真心建议你试用下 meta-api 框架，它已经有了 Grape 框架大约 80% 的同等表达能力；而且，它还是一个文档友好的独一无二的框架。

框架开发进展情况

如何试用和上手

首先，它的上手难度不见得比 Grape 高，因为二者都是啥也不依赖的微型框架。最简单也是最好的上手方案，直接使用我提供的脚手架：

https://github.com/yetrun/web-frame-example

请按照它的说明文档一步一步去做就好。如果需要访问 API 文档，可使用我的 OpenAPI 工具作实时预览。在浏览器地址栏输入：

http://openapi.yet.run/playground

然后内里还有一个地址栏，输入 ws://localhost:9292/api_spec 就好。（前提是项目先用 Rackup 启动了）

关于脚手架的说明：

这是一个纯 Ruby 脚手架，没有用到 Rails. 在使用微型框架时，没有必要引入 Rails，只需要基于 Rack 即可。这个脚手架除了可用于 meta-api 之外，也可以用于 Grape、Sinatra 等，只需要将 meta-api 的部分对应地替换掉即可。

我么摒弃 Rails 的 MVC，不是说要完全摒弃 Rails. 像 ActiveRecord，放在哪里都能用的，而且本身也可作为组件拆分出来单独使用。脚手架集成了几个好用的组件，像 ActiveRecord、Pundit、FactoryBot 等。

上线的项目情况

由于知名度真的很低，再加上我很少宣传，现在项目的使用情况很少。主要是包括我公司的项目，和我业余开发的两个项目：

场景举例

接口的语义和职责

可以这么说，meta-api 这个框架是我这么多年接口开发的理念的总结，其中蕴涵了一些我对接口职责的看法。有些东西通过产品是看不出来的，但通过接口可能暴露出来，从而给系统带来隐患。如果我们一直以一种不负责任、能用即用的态度开发接口，那么系统的安全问题迟早会暴露出来。

举个简单的例子，对于返回用户信息这样的接口（GET /user），密码这个字段不应该在返回实体内列出来的。如果我们只是简单地使用类似

render user.to_json

这样的代码，就会暴露出 user 对象实例能够暴露的所有字段，这样是不安全的。因而，对返回字段的控制是一个框架应该考虑的事情。

但仅仅这样也不够，如果能很好地和文档结合就让事情更加友好了。如果一个接口返回这个字段，我们就在文档中包含它；如果一个接口不返回这个字段，我们就在文档中去掉它。这样，我们只要扫一眼接口文档，就可以知道接口的参数和返回值定义得对或不对，是否合理，有没有隐患等等。无论是后端开发者、前端开发者、系统安全员、架构师都可以通过用与实际代码逻辑一致的接口文档进行交流。

meta-api 框架就是天生为这些使用场景而考虑的。具体来讲，是框架内提供的 JsonSchema 模块来定义接口的实体，包括参数和响应值。例如，对于上面的 GET /user 接口，只需要在字段定义处简单地加上标记 render: false 就可以在返回时去掉 password 字段了：

class UserEntity < Meta::Entity
  property :id, type: 'integer', description: 'ID', param: false
  property :username, type: 'string', description: '用户名'
  property :password, type: 'string', description: '密码', render: false
end

meta-api 框架的 JsonSchmea 模块在设计之初，就秉承了两个理念：

参数和返回值统一定义；
提供了场景的概念，实体统一定义，使用时通过场景予以区分。

这样做只为了一个效果，不作重复性的劳动。就是这样，meta-api 不仅让开发者避免写文档，也要避免开发过程中的无谓的重复劳动。做到了这样，就更有效地保证了接口逻辑与文档的一致性。

篇幅有限，说不了太多。JsonSchema 其实是一个很完备的模式定义工具，它支持各种 JSON 类型以及深层次的嵌套，还包括类型转换、数据验证、当前环境访问等特性。

区分参数和返回值

上面的 UserEntity 实体已经给出了这个示例了。我们在实体定义中，注意到 id 字段，我们不让它作为参数；password 字段，我们不让它作为返回值。这样，无论是参数定义还是实体定义，我们都能引用它了：

post '/users' do
  params do
    param :user, ref: UserEntity, required: true
  end
  status 200 do
    expose :user, ref: UserEntity
  end
end

生成的文档即这样，可以观察一下参数和返回值的字段有什么区别：

这么做保护了你的数据。将 id 字段从参数里去除，不会因为偶然因素导致 id 被莫名地更改。将 password 字段从返回字段里去除，防止别人通过接口窥探到隐私数据。

详情接口返回完整字段，列表接口返回概要字段

详情接口和列表接口返回的字段应该是不一样的。

例如查看文章列表 GET /articles，它的返回消息体可能是：

{
  "articles": [
    { "id": 1, "title": "Article One" },
    { "id": 2, "title": "Article Two" },
    { "id": 3, "title": "Article Three" }
  ]
}

而查看文章详情的接口 GET /articles/1，它的返回消息体应包括富文本内容，也就是 content 字段：

{
  "article": {
    "id": 1,
    "title": "Article One",
    "content": "A long article content..."
  }
}

做到这一点我们也只需要定义一种实体，但要借助场景（scope）辅助实现：

class ArticleEntity < Meta::Entity
  property :id
  property :title
  property :content, scope: 'details'
end

scope 选项定义需要外部提供 details 场景才能用到这个字段。外部提供场景？额，是的……

get '/articles' do
  title '返回文章列表'
  status 200 do
    expose :articles, type: 'array', ref: ArticleEntity
  end
end

列表接口（GET /articles）啥都没干，因此按照默认条件它是无法得到 content 字段的。

get '/articles/:id' do
  scope 'details'
  title '返回文章详情'
  status 200 do
    expose :article, ref: ArticleEntity
  end
end

详情接口（GET /articles/:id）定义了 scope 为 details，则与 ArticleEntity 内部定义不谋而合，这种场景下它会返回 content 字段：

这样做的考虑是保证接口限制消息体的大小。如果一个消息体过大，它会过度地占用带宽从而影响到服务器的响应能力。我亲自遇到过一个接口包含了富文本的详情后导致系统卡顿不能响应的真实情况。

场景是什么？

场景（scope）是 JsonSchema 模块的核心理念，它是静态生成文档能力的最主要工具。因此，它的功能是很强大的。你可以在接口层定义 scope，它同时应用到参数和返回值；你也可以在参数和返回值上单独应用 scope；上层的 scope 会继承到下层（试想一下在 /admin 空间的顶层定义一个 scope: 'admin' 之后会有什么妙用吧）；你甚至可以在运行时传递 scope（但我不建议这么做，这会让它失去文档正确的表达能力）……总之，有什么问题，来问我吧。

创建和更新动作应用不同的参数

你知道吗？你的接口在不同的场景下请求参数的字段应该是不一样的。因此，无脑接受一样的参数类型，而要求前端来区分和传递真的是正确的习惯吗？

现在我说一下场景，还是 UserEntity，我们要求创建用户时包含 password 这个字段，而在更新时不要包含这个字段。现实是很合理的，我们一般把修改密码放在另一个接口去做。

这次我反过来，先定义接口并列举出场景，再来写 UserEntity. 我们定义两个接口，创建用户和更新用户：

post '/users' do
  scope 'create'
  title '创建用户'
  params do
    param :user, ref: UserEntity, required: true
  end
end

put '/user' do
  scope 'update'
  title '更新用户'
  params do
    param :user, ref: UserEntity, required: true
  end
end

下面是我们希望产生的文档：创建用户接口有 password 参数，更新用户接口没有 password 参数。

定义 UserEntity 实体时，我们只需要根据 scope 来规定字段即可。为了避免干扰，我们只关注 password 字段怎么定义：

class UserEntity < Meta::Entity
  property :password, param: { scope: 'create' }, render: false
end

scope: 'create' 我们已经熟悉了，它只接受创建接口。我们还将这一切包装在 param 选项下，因为只有作为参数时我们才做这样的区分。请记住，你可以为参数和返回两种情况定义不同的 scope.

meta-api 框架为每个路由的方法自动创建了 scope，可以直接在实体中引用。例如，UserEntity 中的 password 可以直接改为：
property :password, scope: '$post'
这样，因为创建用户的接口是 POST，其自动传递 scope: '$post'，因此，不需要在路由定义 scope 'create' 也能让用例跑得通。

用局部更新还是全局替换

如果你了解 PUT 和 PATCH 的语义区别，你就知道什么是局部更新，什么是全局替换。meta-api 可以在声明时定义解析参数时使用局部更新还是全局替换的，默认情况是全局替换。

为实体调用 locked(discard_missing: true)，就将行为调整为局部更新：

put '/articles/:id' do
  params do
    param :article, ref: ArticleEntity
  end
end

patch '/articles/:id' do
  params do
    param :article, ref: ArticleEntity.locked(discard_missing: true)
  end
end

在实际调用中，如果传递的参数是（JSON）

{
  "article": {
    "title": "New Article"
  }
}

那么 PUT 方法获取的参数是（Ruby）

{
  article: {
    title: "New Article",
    content: nil
  }
}

PUT 方法获取的参数是（Ruby）

{
  article: {
    title: "New Article"
  }
}

Meta 框架支持为全局情况使用 discard_missing: true 的配置，这样就可以避免在每个路由参数引用实体底下设置 locked(discard_missing: true) 的调用了。不过我还是喜欢做下区分，即创建类的接口用 discard_missing: false，更新类的接口用 discard_missing: true.

场景是可以向下传递的

这里举出一个例子，将 /admin 锚点下的所有接口都添加一个共同的 scope，这样挂载在它下面的所有接口都能应用这个 scope，实现一些共同的目的。

namespace '/admin' do
  meta do
    scope 'admin'
  end

  get '/admin/dashboard' do
    # 将直接应用 'admin' 场景
  end

  # 通过模块引入的接口也能继承场景 'admin'
  apply API::Users
  apply API::Articles
end

这样，我们可以实现一些特殊的需求，比如只有 admin 情况下才能操作和看到的字段：

class ArticleEntity < Meta::Entity
  property :published, type: 'boolean', description: '是否发布上线', scope: 'admin'
end

动态 `if:`

拥有和 Grape Entity 提供的类似的 if: 选项，用于动态渲染字段。

接着上面的例子，如果你将管理员的接口和普通群众的接口放在同一个锚点下（比如都在 /articles 下），希望根据身份决定是否渲染字段，这个时候 if: 选项将派上用场了。

class ArticleEntity < Meta::Entity
  property :published, type: 'boolean', description: '是否发布上线', if: ->{ current_user.admin? }
end

需要注意的是，虽然渲染（包括参数解析）是动态的，但文档只能保持静态的能力，其字段将会在 API 文档中一直显示出来。你的文档描述中最好加上一段解释：

class ArticleEntity < Meta::Entity
  property :published, type: 'boolean', 
                       description: '是否发布上线，仅管理员可操作', 
                       if: ->{ current.admin? }
end

篇尾

项目地址

说了这么多，我还没有说 meta-api 框架的基本情况。

它的 GitHub 地址是，希望大家能投上一票（Star）：

https://github.com/yetrun/web-frame

这篇文章我只介绍了 meta-api 框架与文档相关的能力，但这并不代表它仅限于此。作为一个框架，它的基本素养是齐全的，包括路由组织和定义、异常拦截、数据验证等。它还包含了一个非常友好的错误栈提示，让开发者在遇到问题时容易对应到出错的代码上。

我目前只在国内推广，用中文文档，对国人友好。我希望能补充一下国内 Ruby 框架的空白吧。

作为 Rails 的插件

框架还打算提供一个 Rails 插件的方案，让 Rails 纯 API 开发者享受到 JsonSchema 文档化的便利。使用 Rails 插件的方案，可以复用现有的框架和代码，可作为一个渐进的兼容方案，显得没那么跳脱。

由于开发初期没有作为主要目标，所支持的配套可能尚不完善。我之前也发布过有关 Rails 插件的方案，没有得到响应和回复。也许 Rails 开发者用的还是全栈的较多吧。有需要的同志可以艾特我，我将加速这方面的进程，后续也可能作为一个主要主题予以开发。

希望能得到来自更多伙伴的支持

现如今的框架开发着实没什么市场了，开发这样的一个项目也是因为我当初有需求，正好当时项目组也需要。因为我们是完全的前后端分离的开发组，而我个人比较讨厌就具体字段情况回答太多的问题，我就这样开发了一个新的框架。

目前框架的发展受到了限制，而我个人开发确实耗时耗力。如果能得到大家的帮助，那就更好了，也能作为我继续坚持下去的动力。当然，我更希望有人能和我一起开发，共同维护一个项目。

加入的途径不限，你可以提出 Issue，对教程或代码提出改进意见；或提出 Pull Request，或加群一起讨论提问。

如果你能使用它并正式投产，像我公司那样，我将不胜感激，并倾尽全力为你解决使用上的任何麻烦。

我坐标位于上海，如果有机会，可以组织一次线下的讨论和交流。我可以就框架的实现思路，以及框架的适用场景作出分享。

欢迎大家进群唠嗑

针对项目的前景和发展的方向，我热忱地欢迎大家伙一起来聊聊，因为我本人也是迷茫的。我也担心我的路走偏，听听大伙的心声有助于我避免重复的、无用的工作。（群号是 489579810）

或者使用 GitHub Discussion？看大家觉得哪个地方更好了，可在帖子下留言通知我。

另外，我很乐意接受应用场景的提供。你可以进群来，提出一些场景，我来答复我的框架是不是能够很好地支持。这样既是帮助了你，也是帮助了我，我将不胜感激。

开源一个 Gem，为 Rails 生成 Swagger 文档

yetrun — Tue, 04 Apr 2023 11:51:34 +0800

现实中为 Rails 添加参数验证的 Gems 很多，添加 Swagger 文档生成的也不少，但能够同时支持参数验证、返回值渲染和 Swagger 文档生成的少之又少，而且将这些能力紧密结合在一起的就几乎没有了。

大家伙在团队开发中，是否会有过这些困惑：

缺少一个比较详细的 API 文档，有些甚至没有文档。
文档和实现往往不一致，明明文档中说有这个字段，结果在实际调用时发现没有这个字段，或者反之。
文档很难实现规约，比如参数集的字段与返回值的字段需要区分开来，以及不同场景下返回值的字段也应有所区分。所以，现实中往往只能抛出一个大而全的字段表放在 API 文档中。

如果有，你就真应该看看我的这个 gem：meta-api，它天生就是为了解决这些问题的。我们把 API 文档看成是前后端开发者都需要遵守的契约，不仅是前端调用错误需要报错，后端使用错误也需要报错。

初窥一览

温馨提示：访问仓库 web-frame-rails-example 可查看示例项目。你可以现在就去体验，或者任何时候回过头来体验均可。

安装

要在 Rails 中使用 meta-api，请遵循以下步骤。

第一步，在 Gemfile 中添加：

gem 'meta-api'

然后执行 bundle install.

第二步，在 config/initializers 目录下创建一个文件，例如 meta_rails_plugin.rb，并写入：

require 'meta/rails'

Meta::Rails.setup

第三步，在 application_controller.rb 下添加：

class ApplicationController < ActionController::API
  # 引入宏命令
  include Meta::Rails::Plugin

  # 处理参数验证错误，以下仅是个示例，请根据实际需要编写
  rescue_from Meta::Errors::ParameterInvalid do |e|
    render json: e.errors, status: :bad_request
  end
end

以上步骤完成后，就可以在 Rails 中编写宏命令定义参数和返回值了。

编写示例

下面编写一个 UsersController，作为使用宏命令的示例：

class UsersController < ApplicationController
  route '/users', :post do
    title '创建用户'
    params do
      param :user, required: true do
        param :name, type: 'string', description: '姓名'
        param :age, type: 'integer', description: '年龄'
      end
    end
    status 201 do
      expose :user do
        expose :id, type: 'integer', description: 'ID'
        expose :name, type: 'string', description: '姓名'
        expose :age, type: 'integer', description: '年龄'
      end
    end
  end
  def create
    user = User.create(params_on_schema[:user])
    render json_on_schema: { 'user' => user }, status: 201
  end
end

以上首先使用了 route 命令定义一个 POST /users 的路由，并提供了一个代码块，所有的参数定义和返回值定义都在这个代码块内。当这一切定义就绪之后，实际执行时会带来两个效果：

params_on_schema：它返回根据定义解析后的参数，比如你如果传递了这么一个参数：
```
{
  "user": {
    "name": "Jim",
    "age": "18",
    "foo": "foo"
  }
}
```
它会帮你过滤掉不必要的字段，并且做适度地类型转换，从而让应用内真正获取的参数变成（通过 params_on_schema）：
```
{
  "user": {
    "name": "Jim",
    "age": 18
  }
}
```
这样你就可以放心无虞地将其传递给 User.create! 方法，不用担心任何错误。
json_on_schema：通过它传递的对象会经由返回值定义解析，因为有字段的过滤、类型的转换和数据的验证，后端可以控制哪些字段返回给前端、如何返回以及在字段出错时得到提醒等。比如你的 users 表包括以下字段：
```
id, name, age, password, created, updated
```
根据定义，它只会返回如下字段：
```
id, name, age
```

生成 Swagger 文档

一切皆是以生成 Swagger 文档为核心。

如果你想要生成文档，请按照我的步骤执行。

第一步，想好你的 Swagger 文档放哪？比如我新建一个接口用于返回 Swagger 文档：

class SwaggerController < ApplicationController
  def index
    Rails.application.eager_load! # 需要提前加载所有控制器常量
    doc = Meta::Rails::Plugin.generate_swagger_doc(
      ApplicationController,
      info: {
        title: 'Web API 示例项目',
        version: 'current'
      },
      servers: [
        { url: 'http://localhost:9292', description: 'Web API 示例项目' }
      ]
    )
    render json: doc
  end
end

第二步，为它配置一个路由：

# config/routes.rb

get '/swagger_doc' => 'swagger#index'

第三步，启动应用即可查看到 Swagger 文档的效果，在浏览器内输入：

http://localhost:3000/swagger_doc

JSON 格式的 Swagger 文档映入眼帘。

如果你是使用 Swagger 文档的老人了，应该知道接下来怎么做。如果你不知道，请按照如下步骤渲染 Swagger 文档：
为应用添加跨域支持：
# Gemfile
gem 'rack-cors'

# config/initializers/cors.rb
Rails.application.config.middleware.insert_before 0, Rack::Cors do
  allow do
    origins 'openapi.yet.run'
    resource "*", headers: :any, methods: :all
  end
end
如果你用的是 Google Chrome 浏览器，需要做一些额外的设置才能支持 localhost 域名的跨域。或者你需要将其挂在一个正常的域名下。

打开 http://openapi.yet.run/playground，在输入框内输入 http://localhost:3000/swagger_doc.

至此，一切初试体验完毕，前端可以获得一份定义明确的文档，后端也是严格按照这个文档执行的。后端开发者不用做额外的工作，它只是定义参数、定义返回值，然后，一切就完备了。

用不同的场合响应不同的字段

这一章节提供了一个比较充分的主题，meta-api 如何处理不同场合下的字段区分。不同的场合，比如：

某些字段只用作参数，而某些字段只作为返回值。
用作返回值时，某些接口返回字段 a, b, c，而某些接口返回字段 a, b, c, d.
用作参数时同 2，某些接口用到字段 a, b, c，而某些接口用到字段 a, b, c, d.
如何处理 HTTP 中对 PUT 和 PATCH 请求的语义区分。

这里 meta-api 插件提供了实体的概念，我们可以将字段放到实体里，然后在接口中引用它。实体只用定义一遍，不需要任何的重复定义，并且最重要的是，文档和你的定义能够始终保持一致。请接下去看！

使用实体简化参数和返回值的定义

我们将上例中的参数和返回值归纳为为一个实体：

class UserEntity < Meta::Entity
  property :id, type: 'integer', description: 'ID', param: false
  property :name, type: 'string', description: '姓名'
  property :age, type: 'integer', description: '年龄'
end

然后参数和返回值的定义都可以引用这个实体：

route '/users', :post do
  params do
    param :user, required: true, ref: UserEntity
  end
  status 201 do
    expose :user, ref: UserEntity
  end
end

注意到实体定义中，id 属性有一个 param: false 选项，它表示这个字段只能被用作返回值而不能用作参数。这与之前的定义是一致的。

除了限定字段只能用作返回值外，也可以限定它只能用作参数。在 UserEntity 内添加一个 password 字段作为参数，可以如下定义：

class UserEntity < Meta::Entity
  # 省略其他字段
  property :password, type: 'string', description: '密码', render: false
end

总之，只用写一遍实体，同时用作参数和返回值。

如何根据不同场景返回不同的字段

实际接口运用中，不同的场景返回的字段范畴往往是不同的，那些不分场合一股脑返回同样字段的接口实现是错误的。这里提到的不同的出场景，比方说：

列表页下返回基本字段，详情页返回更多字段。
普通用户查看时只能看到一部分字段，管理员查看时可查看全部字段。

这些都可以用 meta-api 提供的 scope 机制加以区分。我仅以列表页接口举例。

假设 /articles 接口返回文章列表，每一篇文章只用返回：title 字段；/articles/:id 接口需要返回文章详情，每一篇文章需要返回 title、content 字段。定义两个实体会显得繁琐加混乱，只用定义一个实体并用 scope: 选项加以区分：

class ArticleEntity < Meta::Entity
  property :title
  property :content, scope: 'full'
end

这时，列表页接口和详情页接口用如下的方式实现：

class ArticlesController < ApplicationController
  route '/articles', :get do
    status 200 do
      expose :articles, type: 'array', ref: ArticleEntity
    end
  end
  def index
    articles = Article.all
    render json_on_schema: { 'articles' => articles }
  end

  route '/articles/:id', :get do
    status 200 do
      expose :article, type: 'object', ref: ArticleEntity
    end
  end
  def show
    article = Article.find(params[:id])
    render json_on_schema: { 'article' => article }, scope: 'full'
  end
end

与常规实现唯一的变化，就是 show 方法内渲染数据时用到的这一行代码：

render json_on_schema: { 'article' => article }, scope: 'full'

它传递了一个选项 scope: 'full'，告诉实体要同时渲染出 scope 标注为 full 的字段（也就是 content 字段）。

除了在调用时传递特定的选项外，这里还有另外一个技巧，使用 meta-api 提供的锁定技术将引用的实体锁定在特定的选项上。

我们修改一下上例 show 方法的定义和实现，如下：

class ArticlesController < ApplicationController
  route '/articles/:id', :get do
    status 200 do
      expose :article, type: 'object', ref: ArticleEntity.locked(scope: 'full')
    end
  end
  def show
    article = Article.find(params[:id])
    render json_on_schema: { 'article' => article }
  end
end

这里有两点变化：

在引用实体时，我们对实体作了 ArticleEntity.locked(scope: 'full')，它返回新的被锁定的实体。
在渲染数据时，选项 scope: 'full' 不用再传递了。

不要小看这点小小的变化，我们在定义时锁定实体，实际上是在接口设计阶段就将实体的作用范畴定义好了。我的观点是，设计优先于实现，因此我更推荐第二种方案。此外，锁定还会影响到文档的生成，文档中的实体只会渲染出锁定 scope 的字段，不会生成不会返回的其他的字段。这对前端查看文档时更友好。

我们在 ArticleEntity 内添加一个新的用不上的字段：

class ArticleEntity < Meta::Entity
  property :title
  property :content, scope: 'full'
  property :foo, scope: 'foo'
end

则 ArticleEntity.locked(scope: 'full') 不仅实现时只会返回 title、content 字段，文档渲染时也只会出现 title、content 这两个字段。

这一节的思想是：只用写一遍实体，在不同的场合下使用。这条思想同时也是下一节的思想。

参数上的锁定：在参数上区分不同的场合

与返回值一样，参数也需要根据不同的场合修改不同的字段。我们定义一个参数实体：

class ExampleEntity < Meta::Entity
  property :name
  property :age
  property :password, scope: 'master'
  property :created_at, scope: 'admin'
  property :updated_at, scope: 'admin'
end

它设定有两个 scope，在两种场合下能够修改的字段不同。我们在实现时，可以在参数定义时使用锁定技术：

class Admin::UsersController < ApplicationController
  route '/admin/users', :put do
    params do
      param :user, ref: ExampleEntity.locked(scope: 'admin')
    end
  end
  def update
  end
end

class UsersController < ApplicationController
  route '/user', :put do
    params do
      param :user, ref: ExampleEntity.locked(scope: 'master')
    end
  end
  def example
  end
end

这在实现上和文档上能同时响应。

参数上的锁定：处理缺失参数

先声明一个 HTTP 相关的背景。对于缺失的参数，HTTP 提供了两种语义的方法：

PUT 请求需要提供完整的实体，包括所有字段。如果某个字段缺失，将按照该字段传递了一个 nil 值处理。
PATCH 请求只用提供需要更新的字段。如果某个字段缺失，将表示这个字段不需要被更新。

这里面涉及到的是对于参数中缺失值如何处理。换言之，对于实体：

class UserEntity < Meta::Entity
  property :name
  property :age
end

如果用户请求只传递了 { "name": "Jim" }，调用 params_on_schema 会返回什么呢？是

{ "name": "Jim", "age": null }

还是

{ "name": "Jim" }

呢？

两者的区分在于前者将缺失值设为 nil，后者丢弃了缺失值。注意这两种数据作为参数传递到 user.update! 方法中，其效果是不同的。

控制这种效果的方式也是通过锁定设置 discard_missing: 选项。

class UsersController < ApplicationController
  # PUT 效果，默认情况，参数始终返回完整实体
  route '/users/:id', :put do
    params do
      param :user, ref: UserEntity # 或 UserEntity.locked(discard_missing: false)，等效
    end
  end
  def replace
  end

  # PATCH 效果，参数丢弃未传递的字段
  route '/users/:id', :patch do
    params do
      param :ref: UserEntity.locked(discard_missing: true)
    end
  end
  def update
  end
end

总结：只用写一遍实体，在不同的场合下使用。

深入细节

最后，我们讲讲 meta-api 有关细节的一些东西吧。它具备基本的参数验证、默认值和转化等逻辑，详细的内容可参考教程相关部分。如果文档中出现不友好的部分，欢迎提 ISSUE 改进。

默认值

你可以为参数（或实体内的字段）提供默认值，如下：

class UserEntity < Meta::Entity
  property :age, type: 'integer', default: 18
end

数据验证

有一些内建的数据验证器，比如：

class UserEntity < Meta::Entity
  property :birth_date, type: 'string', format: /\d\d\d\d-\d\d-\d\d/
end

或自定义：

class UserEntity < Meta::Entity
  property :birthday, 
    type: 'string', 
    validate: ->(value) { raise Meta::JsonSchema::ValidationError('日期格式不对') unless value =~ /\d\d\d\d-\d\d-\d\d/}
end

枚举

class UserEntity < Meta::Entity
  property :age, type: 'integer', allowable: [1,2,3,4,5,6] # 只允许 6 岁以下儿童
end

多态

真的，它有处理多态的能力，就像 Swagger 文档中提供的那样。我不想在这里讲解了，但请相信，它真的有处理多态的能力。

最后的说辞

啥也不说了，我的项目地址目前是在：

http://github.com/yetrun/web-frame

所有的意见和建议对我都是有用的。

如果你遇到 Bug，或者想要新的特性，请提 ISSUE.

如果你遇到任何使用上的问题，希望快速得到解决，请加群：489579810.

如果这个项目对你有用，请为它添加一个 star，不胜感激。

如果你有兴趣为这个项目贡献，欢迎提供 PR.

我希望为 Rails 提供插件的方式没有对你现在的项目带来任何干扰，并为生成文档方面提供助力。

新写的 Web API 框架今天升级了一波

yetrun — Tue, 03 Jan 2023 11:27:04 +0800

之前就这个框架发过一遍帖子。近期由于新冠疫情，公司业务停摆了，全员停工放假，故而集中精力将先前的框架整理了一波。框架地址：

https://github.com/yetrun/web-frame

现在框架的适用性和稳定性比我第一次发帖时有了大大的提升，已经在我的一个个人项目应用上去（openapi.yet.run），并正在应用在我公司的一个新项目上。希望感兴趣的朋友可以试用之，并提出改进意见。

框架有了名字

框架有了自己的名字：meta-api. 有关取名的思路，可阅读：名称由来。

如何试用

我为此提供了一个脚手架：

https://github.com/yetrun/web-frame-example

这个脚手架没有使用到 Rails 全家桶，而是将 Rails 能用到 ActiveRecord 组件单独抽出来了。如果你想要用的是别的框架如 Sinatra、Grape 等，同时也不想引入 Rails 路由那一套，也可以参考这个脚手架的思路改造。

支持

由于框架尚未成熟，可能会遇到各种问题，我特地建个 QQ 群在线实时答疑。（QQ：489579810）

最后的心声

目前框架已经初步达到可生产应用的程度，但实际效果和稳定性还需更多的项目测试才行。我的个人项目上在运行，公司的项目仍在开发中。最近由于奥密克戎的折磨苦不堪言，对人生更少了点期待，也更愿意沉下心来做点自己的事情。

希望未来更好，且行且珍惜吧！

分享一下最近新写的 Web API 框架

yetrun — Fri, 19 Aug 2022 18:22:40 +0800

11 月 22 日更新：今天上传了新的版本，主要调整了路由编写的语法。以前是链式语法：

route('/users', :post)
  .title('创建一个新用户')
  .params {
    param :user, type: 'object', using: UserEntity
  }
  .do_any {
    # 这里实现你的业务逻辑 ...
  }
  .if_status(201) {
    expose :user, type: 'object', using: UserEntity
  }

现在改成块状语法：

post '/users' do
  title '创建一个新用户'
  params {
    param :user, type: 'object', using: UserEntity
  }
  status(201) {
    expose :user, type: 'object', using: UserEntity
  }
  action {
    # 这里实现你的业务逻辑 ...
  }
end

第二是重新编写了文档，以教程的形式循序渐进地讲解，请看教程。比较重要的章节是有关实体定义的，请看实体定义。

零零总总写了有半年了，虽然现在并不是一个发布的好时机，但是想要先分享出来和大家伙交流一下想法。本来打算先在公司用起来的，不过最近公司没有什么新项目，老项目我也不想换框架了，人力物力呀…… 所以只在自己的个人项目下应用了，目前运转良好。

又是一个轮子，只不过有些不一样的地方。

首先，思想上它是完全面向 API 文档的。也许好多团队写文档会借助于 YAPI 这样的第三方工具，或者直接用 Postman 这样用用例来说话，再不济手写 Markdown. 我在框架里直接生成了 OpenAPI 的规格文档，在开发者实现接口的同时，文档就生成了。例如像下面这样定义一个接口，同时文档就能生成了：

route('/users', :post)
  .title('创建一个新用户')
  .params {
    param :user, type: 'object', using: UserEntity
  }
  .do_any {
    # 这里实现你的业务逻辑 ...
  }
  .if_status(201) {
    expose :user, type: 'object', using: UserEntity
  }

其次，这次将参数和返回值的写法统一起来了。像上面，我们只用了一个 UserEntity，就可以同时定义参数和返回值了，再也不用写两遍了。你的 UserEntity 内部可能是这样写的：

class UserEntity
  property :id, type: 'integer', param: false # 只返回
  property :password, type: 'string', render: false # 只用作参数
  property :name, type: 'string,
  property :age, type: 'integer'
end

其他的功能还有很多，就不想一一列举了。想进一步了解的，可以去看 GitHub 仓库：

https://github.com/yetrun/web-frame

这个框架适合纯 API 后端的场景，即前后端分离。也比较适合团队，基本用一种固定的写法构建 API. 重点是生成对应的文档，前后端不再扯皮（你的文档是这么定义的，怎么你返回的数据是长这样啊之类的云云）。

说实话最近整体的工作节奏都有些慢，受大环境的影响吧。本来打算等到我稳定运行后再发布了，但是这可能还要一阵子，就先预先发布一下看看反馈再说。现在大家运行起来可能有点吃力，因为还缺一个项目脚手架，后面会补上。

如果觉得对你有用，还望支持一下，对我回复个 +1. 如果大家热情足够的话，因为涉及到文档，我感觉上手难度还是有的，到时会建个 QQ 群或微信群做全面的答疑。如果大家热情不高，我就当成一个小众项目在我的团队里使用吧。视反馈而定。

yetrun (Yet Run)

Rails 中实现自定义卡片视图帮助方法的心路历程

实现一个基本的 cards_for 效果

为 cards_for 添砖加瓦所受的伤

meta-api: 版本 0.2.0 小结

主要的核心问题：设计即是实现

Ruby Grape 框架

Rails API

meta-api

静态场景化

最后想说的话

meta-api: 让后端开发者不用再写文档

目录

背景简介

meta-api 工具简介

写代码时同步产出文档

文档与接口的逻辑是一致的

一处编写，到处使用

框架与 Rails 和 Grape 的比较

框架开发进展情况

如何试用和上手

上线的项目情况

场景举例

接口的语义和职责

区分参数和返回值

详情接口返回完整字段，列表接口返回概要字段

创建和更新动作应用不同的参数

用局部更新还是全局替换

场景是可以向下传递的

动态 if:

更多的例子

篇尾

项目地址

作为 Rails 的插件

希望能得到来自更多伙伴的支持

欢迎大家进群唠嗑

开源一个 Gem，为 Rails 生成 Swagger 文档

初窥一览

安装

编写示例

生成 Swagger 文档

用不同的场合响应不同的字段

使用实体简化参数和返回值的定义

如何根据不同场景返回不同的字段

参数上的锁定：在参数上区分不同的场合

参数上的锁定：处理缺失参数

深入细节

默认值

数据验证

枚举

多态

最后的说辞

新写的 Web API 框架今天升级了一波

框架有了名字

如何试用

支持

最后的心声

分享一下最近新写的 Web API 框架

实现一个基本的 `cards_for` 效果

为 `cards_for` 添砖加瓦所受的伤

动态 `if:`