OpenAPI Linter

[reuvenharrison]

We would like to add an OpenAPI linter to oasdiff.

Why is it needed?

• During our work on oasdiff, we noticed how easy it is to make mistakes in oasdiff
• A mistake in oasdiff, may prevent it from working as intended
• In some cases, a mistake may distort the diff results, so we think it is correct to run a linter on the specs before comparing them
• The OpenAPI specification includes many constraints that are difficult to adhere to manually
• Some of the oasdiff specification requirements are vague or misleading

Implementation options:

• Reuse the validation functionality from https://github.com/getkin/kin-openapi.git - seems unsuitable because it throws an error on the first error and we want to report all errors
• Reuse https://github.com/daveshanley/vacuum - the tests in this repo seem insufficient for our needs
• Develop our own linter - see initial work here

Feedback is welcome.

[diskun00]

Hi @reuvenharrison, thanks for nice work on oasdiff! i want to check what's status of openapi linters as we want to do both lint and spec comparison for openapi specs. it would be nice to have both feature provided from one tool for simplicity and consistency.

[reuvenharrison]

Interesting.

I wonder if there is a short list of top-priority lint tests that we could build quickly to get some traction and then expand towards a full blown linting tool for OpenAPI spec.

[diskun00]

hard to say. i guess a partial rule check might not be feasible for lint check. since there is some tool like kin-openapi, maybe it's easier to integrate it as lint part instead of develop a new one from scratch?

[reuvenharrison]

Do you use kin-openapi, for linting?
Is it sufficient for your needs?

[diskun00]

actually openapi-parser:D