Add support for documenting a request URI's matrix variables

[kamaydeo]

The URI specification RFC 3986 defines the possibility of including name-value pairs within path segments. Spring MVC has support for this for a long while.

How do you recommend documenting matrix variables with rest docs? For example: "/cars;color=red;year=2012"

[wilkinsona]

There's no support for it at the moment. At first look, I think the best way to support it would be by adding a new snippet that produces a table of the variables. For your example above, that table would be something like:

Name	Description
color	Color of the car
year	Year the car was produced

If you want to add something yourself, and perhaps contribute it, it shouldn't be too hard to write a TemplatedSnippet subclass that uses some of the code in Spring MVC's RequestMappingInfoHandlerMapping as inspiration for the variable parsing.

[slichtenthal]

I'm not sure it is as easy as that because matrix variables can appear anywhere in the URL and so the location should be documented as well. For example:

/cars/12345;id-type=vin/tires;tire-type=winter

so the url structure is: /cars/{id}/{tires}

and it should be documented that id-type can only come after id and tire-type can only come after tires.

[wilkinsona]

@slichtenthal I probably wasn't clear above. That's no different to path parameters where the URL is included in the snippet. I imagine a similar approach could be taken here.