Swagger yaml - $ref 值必须是符合 RFC3986 的百分比编码 URI答案

【问题标题】：Swagger yaml - $ref values must be RFC3986-compliant percent-encoded URIsSwagger yaml - $ref 值必须是符合 RFC3986 的百分比编码 URI
【发布时间】：2022-11-02 14:06:02
【问题描述】：

我得到了以下 YAML，当我尝试这个时，在 https://editor.swagger.io/ 中，当我使用 [ 和 ] 括号时，我收到“$ref values must be RFC3986-compliant percent-encoded URIs”错误，我尝试对它们进行编码，但响应模式没有得到认可，说参考丢失。关于这种情况下可能出现的问题有什么帮助吗？

swagger: "2.0"
info: 
  title: test
  version: "1.0"
paths:
  /api/TestCustomer:
    post:
      consumes:
        - application/json
        - text/json
      produces:
        - application/json
        - text/json
      parameters:
        - name: request
          in: body
          required: true
          schema:
            $ref: '#/definitions/UpdateTestCustomerRequest'
      responses:
        '201':
          description: Test Response
          schema:
            $ref: '#/definitions/Result[UpdateTestCustomerResponse]'   ***This line results in a error "$ref values must be RFC3986-compliant percent-encoded URIs"

definitions:
  UpdateTestCustomerRequest:
    type: object
    properties:
      CustomerId:
        type: string
      UpdatedBy:
        type: string
  Result[UpdateTestCustomerResponse]:
    type: object
    properties:
      Status:
        format: int32
        enum:
          - 201
        type: integer
      Response:
        $ref: '#/definitions/UpdateTestCustomerResponse'
  UpdateTestCustomerResponse:
    type: object
    properties:
      CustomerId:
        type: string

【问题讨论】：

对此有什么帮助吗？

标签： swagger openapi swagger-2.0 swagger-editor

【解决方案1】：

在 OpenAPI 2.0 中，如果某些模式名称包含特殊字符，则它们必须在 $ref 路径中进行 URL 编码。在$ref 路径中将[ 替换为%5B 和] 与%5D，例如：

# Incorrect
$ref: '#/definitions/Result[UpdateTestCustomerResponse]'

# Correct
$ref: '#/definitions/Result%5BUpdateTestCustomerResponse%5D'

或者更好的是，不要在模式名称中使用特殊字符。

如果/当您迁移到 OpenAPI 3 时，您必须从架构名称中删除 [ ] 字符，因为较新的版本仅允许在架构名称中使用 A..Z a..z 0..9 _ . -。

【讨论】：