Error when parsing converted Files.

[nexon]

I'm currently using swagger-parser to transform Swagger 2.0 Specification to a OpenAPI 3.0.

The problem is that it seems OpenAPIKit doesn't work well with the vendor extension that swagger-parser add to. For example:

This is one of the errors:

Inconsistency encountered when parsing Vendor Extension in the root Document object: Found at least one vendor extension property that does not begin with the required 'x-' prefix. Invalid properties: [ extensions ].**

and is because the swagger-parser adds (to the root of the json file):

"extensions" : {
    "x-original-swagger-version" : "2.0"
  }

Something similar happens when the spec has some named parameters, swagger-parser add the x-codegen-request-body-name to keep track, but OpenAPIKit for some reason doesn't parse it. (and shows the same error that i show above).

[mattpolzin]

All versions of the OpenAPI Specification from 2 onward require specification extension properties to begin with x- prefixes so as far as I am aware, the swagger-parser is creating a malformed document by sticking vendor extensions into an object keyed by the string extensions.

Here is where the specification says the x- prefix is required: https://swagger.io/specification/v3/#specification-extensions Here is where the specification lists all the valid root-level properties ("extensions" is not one of them): https://swagger.io/specification/v3/#openapi-object

Let me know if I am misunderstanding the error you are trying to report.

[nexon]

You are understanding correctly. But if you go to the bottom of the table for the OpenAPI object, you will notice that it says

This object MAY be extended with Specification Extensions.

So it seems that it can be extended in some cases.

[mattpolzin]

Yes, the root document can be extended, but what that means is that the following is allowed:

openapi: 3.0.3
info:
  title: My API
  version: 1.0.0
paths:
  '/hello/world': 
    summary: A simple path
x-original-swagger-version: 2.0

Note that the vendor extension is directly on the root object.

The following is not allowed (note that the extension is nested within "extensions" which is not a valid property at the root of a document):

openapi: 3.0.3
info:
  title: My API
  version: 1.0.0
paths:
  '/hello/world': 
    summary: A simple path
extensions:
  x-original-swagger-version: 2.0

[nexon]

Got it. Thanks. Seems pretty weird that is adding the extension in "extensions" since swagger-parser is an official library.

[mattpolzin]

Yeah, sounds like a surprising bug to me, too. I also went and sanity checked myself against another popular root-document extension, though, and here you can see the Redocly x-tagGroups extension sits right at the root level, not nested within extensions: https://redocly.com/docs/api-reference-docs/specification-extensions/x-tag-groups/

[mattpolzin]

I'm going to close this given that it's an issue with swagger-parser. I don't plan on adding support for a non-standard root attribute (extensions) based on the behavior of a third party tool that I would hope would fix this issue by attaching extensions directly to the root of the document if it was reported as a bug against that project.