Fastify addSchema生成OpenAPI 2.0定义出现def-*前缀 如何自定义有意义名称

问题原因 #

fastify-swagger v4.x版本生成OpenAPI 2.0（Swagger 2.0）格式的定义时，默认不会读取schema的title字段作为定义的键名，只会按照schema的加载顺序自动生成def-数字格式的默认键名。

解决方法 #

方案一（兼容性最高，无需修改现有schema）

注册fastify-swagger插件时新增refResolver配置，直接复用你已设置的title字段作为定义键名，配置示例如下：

fastify.register(require('fastify-swagger'), {
  routePrefix: '/swagger',
  swagger: {
    info: {
      title: '接口文档标题',
      version: '1.0.0'
    },
    // 其他原有swagger配置保持不变
  },
  // 新增自定义引用解析规则
  refResolver: {
    buildLocalReference (json, baseUri, fragment, i) {
      // 优先取自定义title作为键名，无title时 fallback 到默认编号规则
      return json.title || `def-${i}`
    }
  },
  exposeRoute: true
})

配置完成后重新启动服务，生成的Swagger定义就会直接用你设置的title值作为定义的键名。

方案二（适合新增schema场景）

如果不想修改插件配置，也可以直接将addSchema中的$id字段值设置为你想要的定义键名即可：

fastify.addSchema({
  $id: 'PersistenceQueryParams', // 直接写目标键名
  title: "PersistenceQueryParams",
  type: 'object',
  description: 'Persistence Service GET API URL query specification. Applicable for GET API only.',
  properties: {
    // 原有属性配置不变
  },
});

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