Swagger-editor: Semantic error at definitions.Response«Page«EnterpriseProfile»».properties.payLoad.$ref $ref values must be RFC3986-compliant percent-encoded URIs in swagger editor

[karunchinna]

Till yesturday(5/22/2018) it was working fine.

now i am getting this error
Semantic error at definitions.Response«Page«AppServerProfile»».properties.payLoad.$ref
$ref values must be RFC3986-compliant percent-encoded URIs

can u help me. how to resolve this issue.

example yaml:

    - in: body
      name: appServerProfile
      description: appServerProfile
      required: true
      schema:
        $ref: '#/definitions/AppServerProfile'
  responses:
    '200':
      description: App Server Profile modified Successfully
      schema:
        **$ref: '#/definitions/Response«AppServerProfile»'**// here i am getting this errror
    '201':
      description: Created

thanks

Q&A (please complete the following information)

• OS: [e.g. macOS]
• Browser: [e.g. chrome, safari]
• Version: [e.g. 22]
• Method of installation: [e.g. npm, dist assets]
• Swagger-Editor version: [e.g. 3.10.0]
• Swagger/OpenAPI version: [e.g. Swagger 2.0, OpenAPI 3.0]

Content & configuration

Example Swagger/OpenAPI definition:

# your YAML here

Swagger-Editor configuration options:

SwaggerEditor({
  // your config options here
})

?yourQueryStringConfig

Describe the bug you're encountering

To reproduce...

Steps to reproduce the behavior:

1. Go to '...'
2. Click on '....'
3. Scroll down to '....'
4. See error

Expected behavior

Screenshots

Additional context or thoughts

[shockey]

@karunchinna, is the name of your definition Response«AppServerProfile»?

[karunchinna]

@shockey, yes .defination is there in definations also.

[hkosova]

@karunchinna The error is valid. #/foo/bar is a JSON Pointer, and according to the JSON Pointer Specification, special characters in key names must be percent-encoded when a JSON Pointer is used as an URL fragment^[1] (as is the case with $refs). So you need to replace

$ref: '#/definitions/Response«AppServerProfile»'

with

$ref: '#/definitions/Response%C2%ABAppServerProfile%C2%BB'

By the way, if you will be migrating to OpenAPI 3.0, keep in mind that it only allows the characters a-z A-Z 0-9 . - _ in component names. So Response«AppServerProfile» is not a valid model name in OpenAPI 3.0.

---

^[1] JSON Pointer Specification, section 6 (emphasis mine):

A JSON Pointer can be represented in a URI fragment identifier by encoding it into octets using UTF-8 [RFC3629], while percent-encoding those characters not allowed by the fragment rule in [RFC3986].

RFC3986, section 3.5:

fragment    = *( pchar / "/" / "?" )

where

pchar         = unreserved / pct-encoded / sub-delims / ":" / "@"
unreserved    = ALPHA / DIGIT / "-" / "." / "_" / "~"
pct-encoded   = "%" HEXDIG HEXDIG

and ALPHA = A-Z a-z, DIGIT = 0-9.

The characters « and » do not belong to the unreserved set, so they must be percent-encoded when used after the # character in URLs.

[karunchinna]

@shockey thanks, But i am not doing this manually. By default Swagger UI Response is like this only.

[shockey]

@karunchinna, Swagger-UI itself does not influence the key names of your responses. If another library is generating your Swagger definition with these key names, you'll need to file an issue with them 😄

[protegesolutions]

@shockey @hkosova I came across this today as well. Def files that were fine from months ago are now breaking in Editor. It would be really nice if these back-end BREAKING changes were highlighted to us simple users of Editor (please!)

[protegesolutions]

@shockey @hkosova Suggested fix is that supposedly invalid JSON is simply escaped as it probably was being previously. No too difficult, really, and saves all this back-and-forth.

[protegesolutions]

@shockey @hkosova Also, if you make the recommended escaping change to the $ref values (in my case [ and ] to %5B and %5D respectively), you end up with broken client-side - and presumably, server-side - generated code:

    ApiCollection5BString5D AttachmentTags (); instead of ApiCollectionString AttachmentTags ();

    ApiCollection5BCustomFieldCategoryRead5D OpportunityCustomFieldCategories (); instead of ApiCollectionCustomFieldCategoryRead OpportunityCustomFieldCategories ();

This is because the generator removes the % but not the rest of the escape code: %5B -> 5B, %5D -> 5D, etc.

So, essentially, it's now impossible to use Swagger Editor to generate - at least - C# client-side code and probably most of the rest of the code types.

Excellent, well-done!

[shockey]

Hi @protegesolutions:

Def files that were fine from months ago are now breaking in Editor. It would be really nice if these back-end BREAKING changes were highlighted to us simple users of Editor (please!)

Validation changes aren't considered breaking changes, because they don't actually break anything. You're still able to generate, export, and render your definition as you normally can.

We add validators pretty frequently, in order to encourage the authoring of definitions that follow the standards set forth in the OpenAPI Specification. Complaint definitions result in better compatibility across the ecosystem, which is good for everyone.

Suggested fix is that supposedly invalid JSON is simply escaped as it probably was being previously. No too difficult, really, and saves all this back-and-forth.

I'm not sure what you mean here? Invalid JSON isn't the problem here. I'll assume you meant JSON pointer?

Care was taken to make sure that non-escaped pointers continued to resolve, even though they should not, in order to avoid a breaking change for users. See this test in Swagger Client: https://github.com/swagger-api/swagger-js/pull/1322/files#diff-12b5bbbad775a24af3453f63f749f2a2R81

if you make the recommended escaping change to the $ref values (in my case [ and ] to %5B and %5D respectively), you end up with broken client-side - and presumably, server-side - generated code

This is a problem, but the issue here actually lies in Swagger Codegen. Consider opening an issue there - I will follow up on this with the Codegen folks as well.

Hopefully we can get this fixed soon! It's unfortunate that Swagger Codegen isn't following the specification perfectly here, but do note that special characters in key names is a fairly uncommon practice. Things go unnoticed in projects as large as the Codegen, from time to time.

So, essentially, it's now impossible to use Swagger Editor to generate - at least - C# client-side code and probably most of the rest of the code types.

Again, this is caused by Swagger Codegen not being able to handle a valid definition when it's properly escaped. The only thing that changed on our side is that we tell users when they're writing something that's invalid now.

You can still generate code - you can simply disregard the validation error until the Codegen patches the escaping issue.

Excellent, well-done!

This kind of snark is unnecessary, and unwelcome here.

It's not a lot to ask of you to be constructive and assume good faith, in exchange for support and development from us at no cost to you.

No one is trying to ruin your day with these, or any, changes that are made - on the contrary, we strive to make it easier to create OpenAPI definitions that are useful because they follow the rules set by the relevant specifications.

[shockey]

Closing due to inactivity.

This is simply to keep our issue tracker clean - feel free to comment if there are any further thoughts or concerns, and we'll be happy to reopen this issue.

[pedy711]

For:

schema:
            $ref: '#/definitions/Page«User»'

I also get the following error:

Semantic error at paths./api/v1/users/page.get.responses.200.schema.$ref
$ref values must be RFC3986-compliant percent-encoded URIs

when I replace the above line with

schema:
            $ref: '#/definitions/Page%C2%ABUser%C2%BB'

then its client-code (Typescript-Angular) is as follows:

import { PageC2ABUserC2BB } from '../model/pageC2ABUserC2BB';