CODEWITHSUNDEEP
swaggeropenapi
Jaxx
Jaxx

Reputation: 1575

When forward slashes need to be escaped in OpenAPI 3?

I am trying to understand in which case the forward slash needs to be escaped when writing OpenApi specification document. Here (https://swagger.io/docs/specification/using-ref/) is written:

/ and ~ are special characters in JSON Pointers, and need to be escaped when used literally 
(for example, in path names).
For example, to refer to the path /blogs/{blog_id}/new~posts, you would use:
$ref: '#/paths/~1blogs~1{blog_id}~1new~0posts'

In this example the first two forward slashes are not escaped?

Then later the following example is given:

$ref: '../resources/users.yaml'

$ref: '../resources/users-by-id.yaml'

And these paths are not escaped?

In which case all (or part of the) forward slashes need to be escaped with ~1 ?

Upvotes: 1

Views: 1895

Answers (1)

MikeRalphson
MikeRalphson

Reputation: 2393

The JSON Pointer part of a $ref is the part after the # fragment delimiter. Before that is the relative or absolute URI, where forward slashes do not need to be escaped.

In the section following the #, the values of things like pathItem keys which contain forward slashes do need to be escaped.

Upvotes: 1

Related Questions