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

10分钟上手swagger-blocksRails项目接入Swagger UI完整教程附Petstore实战示例【免费下载链接】swagger-blocksDefine and serve live-updating Swagger JSON for Ruby apps.项目地址: https://gitcode.com/gh_mirrors/sw/swagger-blocksswagger-blocks 是一款 Ruby DSL gem让你用纯 Ruby 代码直接编写 Swagger/OpenAPI 接口文档并动态生成实时刷新的 Swagger JSON天然兼容 Swagger UI。本文带你用经典的 Petstore 示例在 10 分钟内完成 Rails 项目接入改完代码刷新页面文档即刻更新——从此告别手写 JSON 的枯燥维护。一、为什么选择 swagger-blocks很多团队用静态 JSON/YAML 文件维护 API 文档接口一改就漏改文档。swagger-blocks 的思路是文档写在代码旁边随代码一起活着。核心特性说明⚡ 实时刷新改代码 → 刷新 Swagger UI文档即刻变化 框架无关Rails、Sinatra 均可纯 Ruby 对象也能用✅ 规范 100% 支持完整覆盖 Swagger 2.0 与 OpenAPI 3.0 特性️ 1:1 命名块名与 Swagger 规范几乎一一对应易上手 环境感知纯 Ruby 动态生成可按环境展示不同 API项目入口为 lib/swagger/blocks.rb所有规范节点参数、响应、Schema 等都以节点形式组织在lib/swagger/blocks/nodes/目录下结构非常清晰。二、一键安装修改 Gemfile 即可 在项目根目录的 Gemfile 中加入一行然后执行bundle installgem swagger-blocks也可以直接用gem install swagger-blocks安装gem 信息见 swagger-blocks.gemspec。三、Petstore 实战三步生成实时 Swagger JSON 下面以官方示例中最经典的 Petstore宠物商店 API为例完整走一遍接入流程。第 1 步在控制器里用 swagger_path 声明接口在你的PetsController中include Swagger::Blocks并用swagger_pathoperation描述接口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.rbOpenAPI 3.0 的 server、requestBody、link 等特性示例见 spec/lib/swagger_v3_blocks_spec.rb。第 3 步创建 Docs 控制器输出 Swagger JSON这是唯一特殊的一步——写一个控制器把所有打过 swagger 标记的类交给build_root_json一键汇总核心实现在 lib/swagger/blocks/root.rbclass 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 endparameter 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 代码Gemfile 加一行安装 swagger-blocks控制器/模型里声明swagger_path、swagger_schema1:1 对应规范Docs 控制器输出 JSONbuild_root_json一键汇总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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考