search

IBM / openapi-to-graphql

Translate APIs described by OpenAPI Specifications (OAS) into GraphQL
https://developer.ibm.com/open/projects/openapi-to-graphql/
MIT License
1.6k stars 206 forks source link

Switch oas-validator to @stoplightio/spectral #410

Open FallingSnow opened 3 years ago

FallingSnow commented 3 years ago

@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 commented 3 years ago

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 commented 3 years ago

@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 commented 3 years ago

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

Here are some reasons I can think of:

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

oas-kit pulse: Screenshot from 2021-07-01 11-32-42

Spectral pulse: Screenshot from 2021-07-01 11-32-32

Alan-Cha commented 2 years ago

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

ardatan commented 2 years ago

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 :)