Failing to validate API Spec without x-hasEquivalentPaths

[Larkenx]

oas-kit/packages/oas-validator/index.js

Lines 1197 to 1199 in b1bba3f

	if (paths[template] && !openapi["x-hasEquivalentPaths"]) {
	should.fail(false,true,'Identical path templates detected');
	}

We have about a hundred API specs we're trying to validate and migrate into a new system, using this dependency to parse and validate the existing API specs. Previously we were using a Java Swagger dependency to do that, but since we're re-platforming to Node.js, we're using this dependency with existing validated specs.

I'm seeing lots of occurences of Identical path templates detected, and I can see in the code it looks for a x-hasEquivalentPaths attribute, but I can't find this documented anywhere on the official swagger spec. https://swagger.io/specification/

Should this validation be turned off entirely or made at least configurable via options?

[MikeRalphson]

Hi, just a note first that the swagger.io site is not the official source for the OpenAPI specification, that would be https://github.com/OAI/OpenAPI-Specification or https://spec.openapis.org/oas/v3.0.3.html

The relevant section of the spec for this validation rule is https://spec.openapis.org/oas/v3.0.3.html#patterned-fields:

| Templated paths with the same hierarchy but different templated names MUST NOT exist as they are identical.

So, no, I don't believe this validation rule should be removed. It can and will cause interoperability problems for your OAS documents to have multiple paths which only differ by the names of the templated parameters (which are of course invisible to the receiving system).

Over at APIs.guru we needed a way to disable this validation per OAS document, so that was the origin of the x-hasEquivalentPaths extension. That effectively is making the rule "configurable via options" as above.

I'm not sure I want to go down the route of making validation rules configurable via options, but would certainly look at any PR you had time to submit.