如何在OpenAPI中标记整个API为已弃用（无需逐个标记操作）

针对你要替代旧REST API、平滑下线且最小化修改量的需求，以下是几种高效方案：

1. 全局中间件/拦截器（修改量最小） #

不管你用的是Spring Boot、Express、Flask还是其他框架，都能通过全局中间件统一处理所有旧REST接口：

• 响应头注入：给所有旧API的响应添加Deprecated: true头，额外可以加Link头指向GraphQL API的入口或文档，比如Link: <https://your-domain/graphql>; rel="alternate"
• 响应体附加警告：在原有响应外层套一层警告信息，不破坏原有业务数据的同时提醒调用方：

  {
    "original_data": {}, // 接口原本返回的数据
    "deprecation_warning": "此REST API已弃用，请切换至GraphQL API"
  }
  

• 调用统计：在中间件里记录旧API的请求详情（路径、调用方IP、时间），方便后续跟踪哪些客户端还在依赖，针对性推进切换

举个Express的极简实现代码：

// 给所有/api前缀的接口加弃用标记
app.use('/api/*', (req, res, next) => {
  // 加响应头
  res.set('Deprecated', 'true');
  res.set('Link', '<https://your-domain/graphql>; rel="alternate"');
  // 包装响应体
  const originalSend = res.send;
  res.send = function(payload) {
    const wrapped = {
      data: typeof payload === 'string' ? JSON.parse(payload) : payload,
      warning: "该REST API已弃用，请使用GraphQL API替代"
    };
    originalSend.call(this, JSON.stringify(wrapped));
  };
  next();
});

2. 网关/路由层统一配置 #

如果旧API有统一的路由前缀（比如/v1/api），直接在网关或路由层面处理，完全不用碰业务代码：

• Nginx示例：

  location /v1/api/ {
    add_header Deprecated true;
    add_header Warning '299 "此API已弃用，请切换至GraphQL"';
    proxy_pass http://your-rest-service;
  }
  

• Spring Cloud Gateway示例：配置全局过滤器给指定路径添加响应头，同样不需要修改后端服务

3. 文档层面批量标记 #

如果用了Swagger/OpenAPI管理API文档，直接给整个旧API分组加弃用标记：

• 在OpenAPI规范中，给旧API对应的tag设置deprecated: true，或者在paths节点全局声明，文档会自动显示弃用标识，前端/客户端开发者一眼就能看到

关键注意点 #

• 过渡期内不要直接返回4xx错误，先通过头信息和警告提示，给客户端足够切换时间
• 可以在警告里明确下线日期，比如Warning: 299 - "此API将于2024-12-31停止服务，请尽快切换"
• 定期统计旧API调用量，等调用量降到阈值后再正式下线

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