如何在OpenAPI 3.0中为路径参数添加示例并解决Azure APIM编辑限制问题

一、OpenAPI 3.0路径参数示例的正确写法 #

别直接在路径参数的example字段填值，改用examples结构，这样导入APIM后既会显示示例，又不会锁死字段。示例代码如下：

openapi: 3.0.3
info:
  title: 示例API
  version: 1.0.0
paths:
  /users/{userId}:
    get:
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
          # 用examples定义示例（单组/多组都支持）
          examples:
            普通用户ID:
              summary: 常规用户ID示例
              value: "user_001"
            管理员ID:
              summary: 管理员用户ID示例
              value: "admin_999"
      responses:
        '200':
          description: 获取用户信息成功

这种写法会让开发者门户里的路径参数默认填充示例值，同时允许开发者修改或清空内容。

二、APIM门户添加路径参数示例的正确步骤 #

直接在参数编辑框的「示例」输入框填值容易锁死字段，正确操作流程：

• 打开目标API的具体操作（比如GET /users/{userId}）
• 切换到「设计」标签页，找到路径参数列表
• 点击对应参数的编辑图标，在弹窗里展开「高级」选项
• 找到「示例」区域，点击「添加示例」，填写名称、说明和值后保存
  按这个流程配置的示例，在开发者门户里是可编辑状态。

三、修复已被锁死的路径参数 #

如果已经出现参数不可编辑的情况，按以下步骤处理：

1. 在APIM门户的API概览页，点击「导出」，选择OpenAPI 3.0格式下载定义文件
2. 打开下载的YAML/JSON文件，找到对应路径参数，删除直接写的example: "xxx"，替换成上面的examples结构
3. 回到APIM门户，导入修改后的OpenAPI定义，覆盖原API配置
4. 重新发布API，刷新开发者门户，参数即可恢复可编辑状态

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