企业官网建设流程全解析

10分钟上手swagger-blocks：Rails项目接入Swagger UI完整教程（附Petstore实战示例）

【免费下载链接】swagger-blocksDefine and serve live-updating Swagger JSON for Ruby apps.项目地址: https://gitcode.com/gh_mirrors/sw/swagger-blocks

swagger-blocks 是一款 Ruby DSL gem，让你用纯 Ruby 代码直接编写 Swagger/OpenAPI 接口文档，并动态生成"实时刷新"的 Swagger JSON，天然兼容 Swagger UI。本文带你用经典的 Petstore 示例，在 10 分钟内完成 Rails 项目接入，改完代码刷新页面，文档即刻更新——从此告别手写 JSON 的枯燥维护。

一、为什么选择 swagger-blocks？🚀

很多团队用静态 JSON/YAML 文件维护 API 文档，接口一改就漏改文档。swagger-blocks 的思路是：文档写在代码旁边，随代码一起"活"着。

项目入口为 lib/swagger/blocks.rb，所有规范节点（参数、响应、Schema 等）都以"节点"形式组织在lib/swagger/blocks/nodes/目录下，结构非常清晰。

二、一键安装：修改 Gemfile 即可 📦

在项目根目录的 Gemfile 中加入一行，然后执行bundle install：

gem 'swagger-blocks'

也可以直接用gem install swagger-blocks安装，gem 信息见 swagger-blocks.gemspec。

三、Petstore 实战：三步生成实时 Swagger JSON 🐕

下面以官方示例中最经典的 Petstore（宠物商店 API）为例，完整走一遍接入流程。

第 1 步：在控制器里用 swagger_path 声明接口

在你的PetsController中include Swagger::Blocks，并用swagger_path+operation描述接口：

class PetsController < ActionController::Base include Swagger::Blocks swagger_path '/pets/{id}' do operation :get do key :summary, 'Find Pet by ID' key :operationId, 'findPetById' key :tags, ['pet'] parameter do key :name, :id key :in, :path key :required, true key :type, :integer key :format, :int64 end response 200 do key :description, 'pet response' schema do key :'$ref', :Pet end end end end end

💡 块名（parameter、response、schema）与 Swagger 规范几乎 1:1 对应，写过 OpenAPI JSON 的人会秒懂。

第 2 步：用 swagger_schema 定义数据模型

接口要引用数据模型（如Pet），在模型类中用swagger_schema声明：

class Pet < ActiveRecord::Base include Swagger::Blocks swagger_schema :Pet do key :required, [:id, :name] property :id do key :type, :integer key :format, :int64 end property :name do key :type, :string end end end

完整复杂的写法（含allOf、数组嵌套等）可参考 spec/lib/swagger_v2_blocks_spec.rb，OpenAPI 3.0 的 server、requestBody、link 等特性示例见 spec/lib/swagger_v3_blocks_spec.rb。

第 3 步：创建 Docs 控制器，输出 Swagger JSON

这是唯一"特殊"的一步——写一个控制器，把所有"打过 swagger 标记"的类交给build_root_json一键汇总（核心实现在 lib/swagger/blocks/root.rb）：

class ApidocsController < ActionController::Base include Swagger::Blocks swagger_root do key :swagger, '2.0' info do key :version, '1.0.0' key :title, 'Swagger Petstore' key :description, '基于 Petstore 示例的 API 文档' end key :host, 'petstore.swagger.wordnik.com' key :basePath, '/api' key :consumes, ['application/json'] key :produces, ['application/json'] end SWAGGERED_CLASSES = [PetsController, Pet, self].freeze def index render json: Swagger::Blocks.build_root_json(SWAGGERED_CLASSES) end end

再在config/routes.rb注册路由：

resources :apidocs, only: [:index]

⚠️ 注意：SWAGGERED_CLASSES中必须包含声明了swagger_root的self，否则会报 "swagger_root must be declared" 错误。

四、把 Swagger UI 指向 /apidocs，立即"活"起来 ✨

启动应用后，将 Swagger UI 的数据源指向上一步的/apidocs路由，完整的接口文档就会自动渲染出来。

最爽的是：修改任何 swagger 代码块后，只需刷新浏览器，文档随之变化——这就是"live-updating"的含义。文档与代码同源，再也不会出现"文档和接口两张皮"的尴尬。

五、进阶技巧：让文档维护更省力 💡

内联 key，告别啰嗦

每个块都支持内联 hash 写法，下面三种写法完全等价：

parameter do key :name, :petId key :in, :path end

parameter name: :petId, in: :path

参数复用，减少重复

在swagger_root中定义公共参数（如species），在任意swagger_path中一行引用，避免每个操作都重复声明。

按环境展示不同 API

因为 JSON 是运行时动态生成的，你可以在 initializer 里根据Rails.env传入不同配置，让开发、预发布、生产环境展示各自不同的接口清单——这是静态 JSON 文件很难做到的。

其他实用能力

• 安全定义：security_definition支持 API Key、OAuth2 等鉴权方式声明；
• 导出文件：build_root_json的结果可直接to_json写入swagger.json文件；
• 动态覆写：对返回的 JSON 做merge，即可临时定制字段。

更多细节可在 README.md 的 Reference 部分找到完整示例。

六、常见问题 FAQ ❓

Q1：我的 Rails 项目没有 swagger_root，报错怎么办？检查SWAGGERED_CLASSES是否包含声明swagger_root的控制器自身（self），这是最常见的遗漏点。

Q2：支持 Swagger 2.0 之外的规范吗？支持。根节点声明key :openapi, '3.0.0'即可切换 OpenAPI 3.0，自动输出components结构，版本判定逻辑见 lib/swagger/blocks/class_methods.rb。

Q3：一定要用 Rails 吗？不是。任何 Ruby Web 框架（Sinatra、Hanami 等）甚至纯 Ruby 对象都可以，核心只需include Swagger::Blocks三个词。

七、总结 🎯

swagger-blocks 用一行include和一行build_root_json，就把"写 API 文档"变成"写 Ruby 代码"：

1. Gemfile 加一行：安装 swagger-blocks；
2. 控制器/模型里声明：swagger_path、swagger_schema1:1 对应规范；
3. Docs 控制器输出 JSON：build_root_json一键汇总；
4. Swagger UI 指向 /apidocs：改代码，刷新即生效。

文档与代码同呼吸，接口变更零维护成本——这正是 swagger-blocks 给 Ruby 开发者带来的最大价值。🎉

【免费下载链接】swagger-blocksDefine and serve live-updating Swagger JSON for Ruby apps.项目地址: https://gitcode.com/gh_mirrors/sw/swagger-blocks