本文介绍在Linux环境下，利用Swagger实现API版本控制的几种常用方法。选择哪种方法取决于你的具体需求。

一、基于URL路径的版本控制:

这是最简单直接的方法。通过在API路径中嵌入版本号来区分不同版本，例如/api/v1/users表示版本1的用户API，/api/v2/users表示版本2的用户API。

在Swagger配置文件(YAML或JSON)中，为每个版本定义独立的路径：

paths:
  /api/v1/users:
    get:
      summary: 获取用户列表 (v1)
      ...
  /api/v2/users:
    get:
      summary: 获取用户列表 (v2)
      ...

二、基于HTTP请求头的版本控制:

这种方法通过自定义HTTP请求头来指定API版本，例如X-API-Version: 1。

宝塔Linux面板11.8.1

宝塔Linux面板11.8.1为官网当前正式版，新增AI建站能力并经过宝塔网站工程师深度调教，开放自定义AI功能API，同时对WAF进行界面重构和深度优化，提升拦截能力与运维效率。

下载

在Swagger配置文件中，定义一个参数来接收版本号：

parameters:
  - name: X-API-Version
    in: header
    description: API版本
    required: true
    type: string
    enum: ["1", "2"]

paths:
  /api/users:
    get:
      summary: 获取用户列表
      parameters:
        - $ref: "#/parameters/X-API-Version"
      ...

三、基于媒体类型的版本控制:

这种方法利用Content-Type或Accept头中的自定义媒体类型来区分版本，例如application/vnd.myapp.v1+json。

在Swagger配置文件中，为每个版本指定对应的媒体类型：

paths:
  /api/users:
    get:
      summary: 获取用户列表
      consumes:
        - application/vnd.myapp.v1+json
        - application/vnd.myapp.v2+json
      ...

总结:

无论选择哪种方法，都务必在API文档中清晰地说明版本控制策略，方便开发者理解和使用不同版本的API。 实际应用中，可以根据项目复杂度和需求选择最合适的方案。

大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！