Switch oas-validator to @stoplightio/spectral

[FallingSnow]

trafficstars

@stoplightio/spectral supports openapi 3.1.0 while oas-validator does not. One noteable drawback seems to be that @stoplight.spectral is much slower but seems to have caught thing even oas-validator didn't; such as operationRef syntax errors.

[FallingSnow]

I should also point out that due to operationRef uri syntax requirements, AKA using the title of the specification in links is invalid, it had to be switched to file based references. That means that link operationRef's need to be defined by file name instead. Since no filename information is passed into openapi-to-graphql I instead added a vendor extension to the spec. You can specify the document's filename by adding a info.x-filename field to the document. This filename can be used in operationRefs. You can see this addition in the example_oas.json and example_oas3.json files.

[Alan-Cha]

@FallingSnow Thank you for this PR! Could you explain some of the reasoning behind this change? I am not very familiar with spectral and I wonder what kind of advantages it has over oas-validator.

I should also point out that due to operationRef uri syntax requirements, AKA using the title of the specification in links is invalid, it had to be switched to file based references.

Thank you for pointing this out! The proposed change to use the file name is a welcome one. Our old method was just the best workaround we could think of at the time. I think your method is much better.

[FallingSnow]

The driving change behind the switch was OAS3.1 support.

Here are some reasons I can think of:

• Has OAS 3.1.0 support.
• Used in/built by stoplight which gives it commercial testing and funding.
• More active

I would also guess that spectral has friendlier error messages since it's main use case is an OpenAPI design application.

oas-kit pulse:

Spectral pulse:

[Alan-Cha]

This seems promising! @ardatan Do you have any opinions on this?

[ardatan]

Personally I think OAS Validation shouldn't be part of the core library but CLI maybe? But if we want to have it, this library seems better than what we have right now :)