matrix parameter type not supported with openapi3

[lintaba]

Describe the bug
openapi 3 (or swagger2) supports matrix parameter style, which looks like this:
/foo/bar;key=value/baz
in this case, the query path should look like this: /foo/bar{;key}/baz.
however its currently not supported, and gives the following error message:
Parameter "key" must be used in path "/foo/bar{;key}/baz".
It most probably comes from https://github.com/stoplightio/spectral/blob/develop/packages/rulesets/src/oas/functions/oasPathParam.ts#L5 , where the regex does not matches ;. Note to mention, that it may also contains asterix (*) and question mark (?) by the specification.

Also it seems it doesnt work even without the ; , when there are more than one parameters are given.

To Reproduce

1. Given this OpenAPI/AsyncAPI document '...'

{
  "openapi": "3.0.0",
  "info": { "title": "matrix failure", "version": "1.0"},
  "servers": [{"url": "http://localhost:3000"}],
  "paths": {
    "/foo{;key}": {
      "parameters": [
        {
          "name": "key",
          "in": "path",
          "schema": {
            "type": "string"
          },
          "required": true,
          "style": "matrix"
        }
      ],
      "get": { "responses": { "200": { "description": "OK"} } } },
    "/foo{key}{another}": {
      "parameters": [
        {
          "name": "key",
          "in": "path",
          "schema": {
            "type": "string"
          },
          "required": true,
          "style": "matrix"
        },
        {
          "name": "another",
          "in": "path",
          "schema": {
            "type": "string"
          },
          "required": true,
          "style": "matrix"
        }
      ],
      "get": { "responses": { "200": { "description": "OK"} } } }
	}
}

2. Run this CLI command:

$ cat .spectral.json 
{\n\t"extends": ["spectral:oas", "spectral:asyncapi"]\n}
$ spectral lint example.json
[...]
 8:28    error  path-params                 Parameter "key" must be used in path "/foo{;key}".             paths./foo{;key}.parameters[0]
  30:9    error  path-params            Parameter "another" must be used in path "/foo{key}{another}".                            paths./foo{key}{another}.parameters[1]
 40:13    error  path-params            Operation must define parameter "{keyanother}" as expected by path "/foo{key}{another}".  paths./foo{key}{another}.get

Expected behavior
Expected to support matrix parameters :)

Environment (remove any that are not applicable):

• Library version: 6.0.0
• OS: osx

Additional context

related specs: https://swagger.io/docs/specification/serialization/#query

[P0lip]

Hey!
Your findings are indeed correct. We don't support matrix parameter type just yet.
The support for that would need to be added somewhere in https://github.com/stoplightio/spectral/blob/develop/packages/rulesets/src/oas/functions/oasPathParam.ts as you indicated in the issue.
Would you be open to tackling this issue?
Happy to provide you any support you may need to get started.

[lintaba]

Hey!

I've tried to set up a working copy to check whether my changes are correct, but i hadnt succeeded. (cloned the repo, but havent found a working entry point :/ ) If you can help me set it up, i can check if my fix is correct.

However I think the following change would do the trick:
https://github.com/stoplightio/spectral/blob/develop/packages/rulesets/src/oas/functions/oasPathParam.ts#L5

const pathRegex = /(\{;?\??[a-zA-Z0-9_-]+\*?\})/g;

and probably this also needed:
https://github.com/stoplightio/spectral/blob/develop/packages/rulesets/src/oas/functions/oasPathParam.ts#L121

      const p = match[0].replace(/[{}?*;]/g, '');

Also I'm not sure about the reasoning behind that trailing + in the pathRegex. It now matches for {foo}{bar} as one match, instead of two. Is it the intended behaviour? My proposed change would change it, however that may break existing behavior. It definitely not compatible with matrix parameter type (or needs a bit more hack to slice it later)

[lintaba]

I made a PR with these changes, but cannot validate/test it on my own :/

[P0lip]

Hey!
You can verify the changes over here https://github.com/stoplightio/spectral/blob/develop/packages/rulesets/src/oas/__tests__/path-params.test.ts

Just add any examples, and the expected results and then run yarn test.jest packages/rulesets/src/oas/__tests__/path-params.test.ts

[lintaba]

Thanks @P0lip, with your help I was able to write two tests for the given examples. Both cases are covered, tests are green for these changes (and also fails without my fix.)

#1864

[stoplight-bot]

🎉 This issue has been resolved in version @stoplight/spectral-rulesets-v1.2.6 🎉

The release is available on npm package (@latest dist-tag)

Your semantic-release bot 📦🚀