OpenAPI 2.0/3.x.y - validation of Path Templating

[char0n]

We are currently not able to validate and resolve Path Templating. I have created low level parser, validator and resolver library for OpenAPI Path Templating here: https://github.com/char0n/openapi-path-templating

openapi-path-templating is applicable for: OpenAPI 2.0 and 3.x.y.

We want to use it for every case related to Path Templating.

Warning

openapi-path-templating library doesn't handle computing appropriate Parameter Objects to be resolved against the template expression.

---

I actually see two different linting rules here and I do understand and approach them differently (correct me if I'm wrong).

Rule 1

We want a linting rule that validates if the template expressions defined within the URL are all present in the appropriate Parameter Objects.

Rule 2

We want a linting rule that validates that user did not forget to define template expressions for all the appropriate Parameter Objects.

For the purpose of this implementation I will assume we're talking about Rule 1.

---

There are multiple layers that we need to implement to achieve the final goal described in Rule 1.

Low level Path Templating handling

I've already had a code for this on my local dev computer. I've consolidated the code and pushed with (along with the documentation) to https://github.com/char0n/openapi-path-templating. The library is not yet released, I will release it probably during today. The library handles all the low level complexities and corner cases of parsing, validating and resolving the Path Templating.

The library can distinguish if the URL contains Path Templating or not.

Above is an excerpt from OpenAPI 3.x.y spec, which tells us how to handle escaping of "generic syntax" characters

High level Path Templating handling

Above OpenAPI 3.x.y excerpt tells us how to handle Path Templating

Collecting Parameter Objects

So, what we need to do it to collect all Parameter Objects from Path Item Object directly mapped to URL with Path Templating and all Parameter Objects from every Operation Object mapped from Path Item Object under the HTTP verb. (I'll help you with querying those out from ApiDOM later).

When we have all the Parameter Objects we have to apply following algorithms defined by OpenAPI:

Applies to both PathItem.paramters and Operation.parameters

The list MUST NOT include duplicated parameters.

A unique parameter is defined by a combination of a name and location.

Applies to Operation.parameters

If a parameter is already defined at the Path Item, the new definition will override it but can never remove it.

So basically we'll have to create a unique function specific to list of Parameter Objects or reuse the already implemented logic of normalize-parameters refractor plugin which already does this.

Matching Path Templating with Parameter Objects

Now we need to use https://github.com/char0n/openapi-path-templating to parse the relative URI Reference (with possible Path Templating) and match the parsed template-expression tokens against the collected Parameter Object.

---

And we must not forget the exception described in the OpenAPI excerpt, already mentioned above. If the Path Item Object is empty, the the Path Templating doesn't need to be matched with path template expressions. We'll just skip it. Emptiness of the Path Item Object is defined by lack of all fixed fields (Specification Extensions MAY be present).

OpenAPI excerpt

[char0n]

openapi-path-templating just released as https://www.npmjs.com/package/openapi-path-templating

[char0n]

We need to attach the metadat to URL Template (keys in Paths Object). That way our linting function will receive element, which represents the URL Template.

Then in linting function we can do following:

element.parent === MemberElement
element.parent.value === Path Item Object

And that basically is what we want, to be able to access contextual Path Item Object, depending on the current URL Template.

This applies to OpenAPI 2.0/3.0.x/3.1.0

---

Addressed by #3532