swagger-blocks源码剖析InternalHelpers如何智能合并多类节点$ref重写背后的双版本玄机【免费下载链接】swagger-blocksDefine and serve live-updating Swagger JSON for Ruby apps.项目地址: https://gitcode.com/gh_mirrors/sw/swagger-blocksswagger-blocks 是一款面向 Ruby 应用的 Swagger/OpenAPI JSON DSL帮你用纯 Ruby 代码块定义并实时生成可自动刷新的 Swagger JSON兼容 Swagger 2.0 与 OpenAPI 3.0 双版本。它的核心魅力在于把 API 文档定义分散在 Controller、Model 等多个类里请求时由InternalHelpers一键智能合并成完整文档。本文带你深入源码拆解 internal_helpers.rb 的多类节点合并算法以及$ref引用路径重写背后的双版本玄机。 30秒看懂 swagger-blocks 的架构整个库只有 4 个核心文件撑起骨架模块文件职责DSL 入口swagger/blocks/root.rb对外提供build_root_json组装最终 JSON合并引擎swagger/blocks/internal_helpers.rb收集并合并多个类的节点数据节点基类swagger/blocks/node.rb所有节点的基类负责版本识别与$ref重写类级 DSLswagger/blocks/class_methods.rb注入swagger_root/swagger_path/swagger_schema等使用方式极其简单——任何 Ruby 类include Swagger::Blocks后即可声明文档片段最后在文档控制器中一行代码生成全量 JSON见 README.md 中 Docs controller 示例render json: Swagger::Blocks.build_root_json(SWAGGERED_CLASSES) 正因为 JSON 是请求时动态构建的你改完代码刷新页面文档就自动更新——这就是 live-updating 的设计本意。 InternalHelpers多类节点合并的三步走算法当你把PetsController、Pet、ErrorModel等一堆类传给build_root_json时真正干活的是 parse_swaggered_classes。它的合并过程可以拆成三步第一步向每个类盘点节点资产遍历所有传入的类通过私有方法 _swagger_nodes 取回各自积累的节点swagger_nodes swaggered_class.send(:_swagger_nodes)每个类在声明swagger_path、swagger_schema、swagger_component时已经把节点存进了类级别的实例变量这里一次性取走。第二步Path 与 Schema 的 Map 级合并Swagger 2.0 的接口路径和模型定义全部走哈希合并path_node_map.merge!(swagger_nodes[:path_node_map]) schema_node_map.merge!(swagger_nodes[:schema_node_map])妙处在于/pets写在 Controller A、/orders写在 Controller B模型Pet定义在 Model 里——分属不同类的节点在merge!后自动汇成一张完整地图类与类之间零耦合。第三步v3 Components 的按项合并OpenAPI 3.0 把所有可复用资源收拢进components节点。合并时不能粗暴整体替换否则后一个类会吃掉前一个类的定义。merge_components 针对 7 个子项逐一合并merge_components(component_node, swagger_nodes, :examples) merge_components(component_node, swagger_nodes, :parameters) merge_components(component_node, swagger_nodes, :schemas) # ... 共 7 项逻辑是先确保目标桶存在再把源桶内容 merge 进来因此多个类各自声明的 schema、参数、响应体互不覆盖。这 7 个子项的声明入口都在 component_node.rb 中。唯一性守门员limit_root_node合并完还要过一道校验limit_root_node一个swagger_root都没有 → 抛DeclarationError: swagger_root must be declared出现两个及以上 → 抛DeclarationError: Only one swagger_root declaration is allowed.错误类型定义在 errors.rb——这是很多新手漏掉文档控制器里的self后最常遇到的报错。⚠️ 小细节合并是后者覆盖前者的语义。同名 path/schema 若想叠加声明而非覆盖应在同一个类里重复声明同名节点——class_methods.rb 会用instance_eval把新声明合并进已有节点而不是新建。 $ref 重写的双版本玄机源码里最精巧的部分藏在 node.rb 的 as_json 方法中。你在 DSL 里写引用时只写名字key :$ref, :Pet而最终 JSON 里出现的必须是完整路径。版本不同路径前缀完全不同版本目标节点类型重写结果2.0任意 schema#/definitions/Pet3.0SchemaNode#/components/schemas/Pet3.0LinkNode#/components/links/Pet3.0ParameterNode#/components/parameters/Pet3.0ResponseNode#/components/responses/Pet3.0RequestBodyNode#/components/requestBodies/Pet3.0ExampleNode#/components/examples/Pet玄机有二其一版本自动探测。每个节点无需手动指定版本Node#version 会检查数据里是swagger: 2.0还是openapi: 3.0.0自动判断再配合 is_swagger_2_0? / is_openapi_3_0? 两个判定方法让同一套节点树在两个版本的 JSON 结构间变形。其二外部引用不动。static_ref? 用正则识别以#/或http(s)://开头的值——已经写全路径的内部引用或跨文档 URL 引用会被原样保留绝不重复加前缀。最后root.rb 的 build_root_json 根据版本把节点挂到不同位置2.0 挂pathsdefinitions3.0 挂pathscomponents再调用as_json(version:)完成全树递归重写。同一份 Ruby 代码两种标准各得其所——这就是双版本玄机的完整闭环。 快速上手三步走声明根节点在文档控制器里include Swagger::Blocks用swagger_root声明key :openapi, 3.0.0v3或key :swagger, 2.0v2及info信息分散定义Controller 里写swagger_pathModel 里写swagger_schema复用资源写swagger_component一行出文档render json: Swagger::Blocks.build_root_json(SWAGGERED_CLASSES)把self也放进列表别漏了否则没有 root 会报错完整可运行的声明范例见 spec/lib/swagger_v2_blocks_spec.rb 与 spec/lib/swagger_v3_blocks_spec.rbGemfile 集成方式参考 Gemfile。 一句话总结swagger-blocks 的精髓就藏在两个文件里internal_helpers.rb用 Map 合并 按项合并把分散在多类中的节点缝成一张完整文档node.rb用版本感知的$ref重写让同一份定义同时兼容 Swagger 2.0 与 OpenAPI 3.0。理解了这两处你就掌握了它改代码即更新文档的全部魔法。【免费下载链接】swagger-blocksDefine and serve live-updating Swagger JSON for Ruby apps.项目地址: https://gitcode.com/gh_mirrors/sw/swagger-blocks创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 swagger-blocks源码剖析：InternalHelpers如何智能合并多类节点，$ref重写背后的双版本玄机
swagger-blocks源码剖析InternalHelpers如何智能合并多类节点$ref重写背后的双版本玄机【免费下载链接】swagger-blocksDefine and serve live-updating Swagger JSON for Ruby apps.项目地址: https://gitcode.com/gh_mirrors/sw/swagger-blocksswagger-blocks 是一款面向 Ruby 应用的 Swagger/OpenAPI JSON DSL帮你用纯 Ruby 代码块定义并实时生成可自动刷新的 Swagger JSON兼容 Swagger 2.0 与 OpenAPI 3.0 双版本。它的核心魅力在于把 API 文档定义分散在 Controller、Model 等多个类里请求时由InternalHelpers一键智能合并成完整文档。本文带你深入源码拆解 internal_helpers.rb 的多类节点合并算法以及$ref引用路径重写背后的双版本玄机。 30秒看懂 swagger-blocks 的架构整个库只有 4 个核心文件撑起骨架模块文件职责DSL 入口swagger/blocks/root.rb对外提供build_root_json组装最终 JSON合并引擎swagger/blocks/internal_helpers.rb收集并合并多个类的节点数据节点基类swagger/blocks/node.rb所有节点的基类负责版本识别与$ref重写类级 DSLswagger/blocks/class_methods.rb注入swagger_root/swagger_path/swagger_schema等使用方式极其简单——任何 Ruby 类include Swagger::Blocks后即可声明文档片段最后在文档控制器中一行代码生成全量 JSON见 README.md 中 Docs controller 示例render json: Swagger::Blocks.build_root_json(SWAGGERED_CLASSES) 正因为 JSON 是请求时动态构建的你改完代码刷新页面文档就自动更新——这就是 live-updating 的设计本意。 InternalHelpers多类节点合并的三步走算法当你把PetsController、Pet、ErrorModel等一堆类传给build_root_json时真正干活的是 parse_swaggered_classes。它的合并过程可以拆成三步第一步向每个类盘点节点资产遍历所有传入的类通过私有方法 _swagger_nodes 取回各自积累的节点swagger_nodes swaggered_class.send(:_swagger_nodes)每个类在声明swagger_path、swagger_schema、swagger_component时已经把节点存进了类级别的实例变量这里一次性取走。第二步Path 与 Schema 的 Map 级合并Swagger 2.0 的接口路径和模型定义全部走哈希合并path_node_map.merge!(swagger_nodes[:path_node_map]) schema_node_map.merge!(swagger_nodes[:schema_node_map])妙处在于/pets写在 Controller A、/orders写在 Controller B模型Pet定义在 Model 里——分属不同类的节点在merge!后自动汇成一张完整地图类与类之间零耦合。第三步v3 Components 的按项合并OpenAPI 3.0 把所有可复用资源收拢进components节点。合并时不能粗暴整体替换否则后一个类会吃掉前一个类的定义。merge_components 针对 7 个子项逐一合并merge_components(component_node, swagger_nodes, :examples) merge_components(component_node, swagger_nodes, :parameters) merge_components(component_node, swagger_nodes, :schemas) # ... 共 7 项逻辑是先确保目标桶存在再把源桶内容 merge 进来因此多个类各自声明的 schema、参数、响应体互不覆盖。这 7 个子项的声明入口都在 component_node.rb 中。唯一性守门员limit_root_node合并完还要过一道校验limit_root_node一个swagger_root都没有 → 抛DeclarationError: swagger_root must be declared出现两个及以上 → 抛DeclarationError: Only one swagger_root declaration is allowed.错误类型定义在 errors.rb——这是很多新手漏掉文档控制器里的self后最常遇到的报错。⚠️ 小细节合并是后者覆盖前者的语义。同名 path/schema 若想叠加声明而非覆盖应在同一个类里重复声明同名节点——class_methods.rb 会用instance_eval把新声明合并进已有节点而不是新建。 $ref 重写的双版本玄机源码里最精巧的部分藏在 node.rb 的 as_json 方法中。你在 DSL 里写引用时只写名字key :$ref, :Pet而最终 JSON 里出现的必须是完整路径。版本不同路径前缀完全不同版本目标节点类型重写结果2.0任意 schema#/definitions/Pet3.0SchemaNode#/components/schemas/Pet3.0LinkNode#/components/links/Pet3.0ParameterNode#/components/parameters/Pet3.0ResponseNode#/components/responses/Pet3.0RequestBodyNode#/components/requestBodies/Pet3.0ExampleNode#/components/examples/Pet玄机有二其一版本自动探测。每个节点无需手动指定版本Node#version 会检查数据里是swagger: 2.0还是openapi: 3.0.0自动判断再配合 is_swagger_2_0? / is_openapi_3_0? 两个判定方法让同一套节点树在两个版本的 JSON 结构间变形。其二外部引用不动。static_ref? 用正则识别以#/或http(s)://开头的值——已经写全路径的内部引用或跨文档 URL 引用会被原样保留绝不重复加前缀。最后root.rb 的 build_root_json 根据版本把节点挂到不同位置2.0 挂pathsdefinitions3.0 挂pathscomponents再调用as_json(version:)完成全树递归重写。同一份 Ruby 代码两种标准各得其所——这就是双版本玄机的完整闭环。 快速上手三步走声明根节点在文档控制器里include Swagger::Blocks用swagger_root声明key :openapi, 3.0.0v3或key :swagger, 2.0v2及info信息分散定义Controller 里写swagger_pathModel 里写swagger_schema复用资源写swagger_component一行出文档render json: Swagger::Blocks.build_root_json(SWAGGERED_CLASSES)把self也放进列表别漏了否则没有 root 会报错完整可运行的声明范例见 spec/lib/swagger_v2_blocks_spec.rb 与 spec/lib/swagger_v3_blocks_spec.rbGemfile 集成方式参考 Gemfile。 一句话总结swagger-blocks 的精髓就藏在两个文件里internal_helpers.rb用 Map 合并 按项合并把分散在多类中的节点缝成一张完整文档node.rb用版本感知的$ref重写让同一份定义同时兼容 Swagger 2.0 与 OpenAPI 3.0。理解了这两处你就掌握了它改代码即更新文档的全部魔法。【免费下载链接】swagger-blocksDefine and serve live-updating Swagger JSON for Ruby apps.项目地址: https://gitcode.com/gh_mirrors/sw/swagger-blocks创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考