如何移除swagger_yard生成的OpenAPI.yml中的Ruby类型前缀？

给你几个实用的解决办法：

1. 配置swagger_yard强制转成原生类型 #

在项目的config/initializers/swagger_yard.rb初始化文件里添加序列化规则，把YARD的特殊对象直接转成普通字符串：

SwaggerYard.configure do |config|
  config.serializer = lambda do |object|
    # 把Docstring对象转成纯文本
    if object.is_a?(YARD::Docstring)
      object.to_s
    # 把模块/类对象转成名称字符串
    elsif object.is_a?(YARD::CodeObjects::ModuleObject) || object.is_a?(YARD::CodeObjects::ClassObject)
      object.name.to_s
    else
      object
    end
  end
end

重新生成OpenAPI文档后，那些Ruby类型标识就会消失。

2. 用脚本后处理生成的YAML文件 #

如果不想改gem配置，直接写个Ruby脚本清理已生成的openapi.yml：

require 'yaml'

# 读取原始文件
yaml_data = YAML.load_file('openapi.yml')

# 递归清理所有YARD特殊对象
def clean_up(obj)
  case obj
  when Hash
    obj.each { |k, v| obj[k] = clean_up(v) }
  when Array
    obj.map! { |item| clean_up(item) }
  when YARD::Docstring
    obj.to_s
  when YARD::CodeObjects::ModuleObject, YARD::CodeObjects::ClassObject
    obj.name.to_s
  end
  obj
end

# 处理后写入新文件
cleaned_data = clean_up(yaml_data)
File.write('cleaned_openapi.yml', YAML.dump(cleaned_data))

运行这个脚本后，cleaned_openapi.yml就是干净的版本，适合文档站点和SDK生成工具解析。

3. 定制swagger_yard的序列化逻辑 #

如果上面的方法都不够，直接修改swagger_yard的源码：找到生成summary、description以及模型引用的代码部分，把YARD对象的调用改成to_s或者直接取名称，避免序列化整个Ruby对象。比如在生成接口描述时，用docstring.to_s代替直接序列化Docstring对象。

内容的提问来源于stack exchange，提问作者RandonneurLibre