When referencing other other elements in an OpenAPI document, how does one encode non-URI-safe strings?
An example of what I mean
Here I have a response in one operation (default
in /path/one
), and I'm trying to reference this response from another operation (default
in /path/two
). To get the URI fragment to given response, I need to include a key (/path/one
) which has URI-forbidden characters (/
):
openapi: 3.0.0
paths:
/path/one:
get:
responses:
default:
description: A normal response
content:
application/json:
schema:
type: string
/path/two:
get:
responses:
default:
# This is the important part
$ref: "#/paths/%2path%2one/get/responses/default"
As demonstrated above, I'd do this by simply URL-encoding the problematic parts.
The reason I'm asking this question, is because on https://apis.guru I found an OpenAPI document (this one: https://api.apis.guru/v2/specs/brex.io/2021.12/openapi.yaml) where they are using the ~
character to "encode" the /
character.
Is this standard or is this a one-of issue with said OpenAPI document?