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

Question

当我尝试此操作时，在https://editor.swagger.io/我得到了"$ref值必须是符合RFC3986的编码URI百分比"；错误：当我使用[和]括号时，我尝试对它们进行编码，但响应模式无法识别，表示缺少引用。关于这种情况下可能出现的问题，有什么帮助吗？

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

Answer 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 _ . -。