Add support for Matrix type parameters #69
Comments
|
Can someone point to an implementation like this outside of JAX-RS? |
|
I don't know of any concrete implementation, but a very good language and framework agnostic overview of how URIs are constructed and how they should be parsed can be found here: |
|
+1 I was just about to open an issue on this. We make extensive use of Matrix Parameters on our API and we are looking at Swagger to document our API. |
|
+1 just ran into this problem myself. Using Play2. We also have a project using Jersey that needs matrix param support. |
|
+1 we have the same need of documenting a set of APIs that use matrix parameters. It would be great to have support for them ! |
|
Spring MVC also supports matrix variables (since 3.2 I think). |
|
Outside the Java world, we were unable to find any other implementations and decided to not include it in Swagger 2.0. I will close this issue for now and mark it as a proposal for the next version. However, I believe that if we don't find any other implementations by then, it will be rejected. |
|
+1 for this |
|
@sterowney - out of curiosity, which library do you use to expose an API with matrix params? |
|
Apache CXF (so its another JAX-RS) category. I will take a look at the code see if there is anything I can contribute to, but on googling why it didn't work, this popped up! |
|
We're not at the point of changing code to support it, we first need to decide whether to support it in the spec. I can tell you we decided to not add it to the 2.0 spec, mostly because we couldn't find any other implementations outside of JAX-RS, and it's really not that common in use. |
|
We've implemented services using matrix params in Jersey, Play 2, Akka-http/Spray. These services are in production. We have used swagger but the swagegr docs are broken due to swagger not supporting matrix params properly. Therefore we are only able to use swagger for limited internal dev docs and are not able to give them to customers directly. |
|
I do agree with @webron that we don't plan to change the spec to support one specific framework. There may be ways to handle your case, though. Could you please share some examples of how you're using matrix params? |
|
Sure. I'll give you one scenario where matrix parameters are very useful in a REST api. Take this api GET /project/abc/entity/foo That should look fairly familiar Now lets add ability to access resources inside the foo entity like so. The user can add any structure they like. /project/abc/entity/foo/assets/foo.jpg I want to access all these things with relative paths from one asset to another... like Inside bing.html, I can reference ../../bar.png But here's where matrix params come in. If I introduce an orthogonal concept such as versioning within the hierarchy. Let's say I want to have the abiliyy to access specific versions of "afolder". I could put the version in the path like so. /project/abc/entity/foo/assets/afolder/version/123/bing.html Neither of these above do what I need which is to attach basically a qualifier into a path segment However using Matrix params I can write and my relative paths will still work because the matrix param does not affect relative navigation. I also is clear what is the name of the path segment that the user can choose and which is the matrix param which is artifact generated by the system. You might also use in multiple segements like This stack overflow answer on query vs matrix is spot on. http://stackoverflow.com/questions/401981/when-to-use-query-parameters-versus-matrix-parameters especially: "matrix parameters are not resources, they are aspects that help reference a resource in an information space that is difficult to represent within a hierarchy" |
|
This may be eventually solved if we expand support for some more aspects of RFC6570 (as some feature requests ask for it), but it will not be in the form of 'matrix params' but rather as an extension of path parameters (which is fine, it's just semantics). |
|
I would also really like to have matrix parameters somehow supported. We use them in several of our services. The problem is that this is not just a minor shortcoming of our documentation in that particular spot. Not having matrix parameters supported in swagger means that if you have a single operation which comprises a matrix param and a body param or more than one matrix param (and we frequently have these situations in our services), we are not able to use swagger-core at all. We consider swagger-core the key reason why we use (or want to use) swagger but this tiny problem renders it unusable for us. |
|
@detached has a addMatrixParam branch of |
|
👍 |
|
@crehn I'm curious… If swagger-core suddenly supported matrix parameters, what would you start doing with it? Why do you want to use it? What problems will it solve for you? |
|
Our projects are using matrix parameter all over the place. If swagger doesn't support it, it is useless for us. We want to use swagger to document our resources as they are, without adding to mutch additional annotations or duplicating documentation. |
|
@earth2marsh One of the key principles of documentation is that the farther away it is from the code the more abstract and generalized it needs to be. Extreme case: documenting private methods in a separate text document is pointless as a) this information changes frequently and b) nobody wants to open a separate document to look up such details. Vice versa documenting something like constraints of the enterprise architecture directly in the code is equal to burying it where nobody will ever find it. Abstract and generalized information ages slowly and is not tied to specific parts of the code. They should be documented separately. Information on single methods ages fast and it is tied to very specific parts of the code. You want this kind of documentation close to the described method. Furthermore duplicating information in docs is similarly harmful than duplicating code. It's a violation of the DRY principle with all its negative effects. When I want to document the operations of a REST interface (and I think that's normally a good idea), I would like to adhere to the principles described above. And swagger-core provides these capabilities. You have proximity by using annotations and you avoid duplication as swagger-core reads the relevant information in part directly from the DTOs and the jax-rs annotations you place there anyway to write your service. In my eyes this is really the key feature of swagger. If swagger wasn't language agnostic, didn't have a strict spec, and the UI would be less nice-looking, I would still use it if and only if it provided me a way to create documentation on the right abstraction level and without duplication. In the past I've used JavaDoc to document my REST interfaces. Despite the proximity, the fact that I have to repeat certain information makes it really painful to maintain the docs. So I'm really happy that I can use swagger for some of my services. Unfortunately I cannot use it for those comprising matrix params. And as I've described above: swagger without swagger-core is -- in my eyes -- pointless. It's just like a more fancy wiki page. In such a case I'd rather use JavaDoc. This might be less colorful but at least it is versioned with the code and provides proximity. tl;dr: swagger-core is the interesting part of swagger. The other stuff is just nice to have. |
|
@t1 I'm afraid a PR to the spec is not going to help at this point. The way I see it right now,the requirement is, to an extent, clear. We may still need to hash out details and edge cases, but before that, unlike some other feature, I'm still not convinced this should be added to the spec, at least directly as 'support matrix params'. If the people involved in this issue would like to hash out the details, you're more than welcome. In this case create a proposal, not s PR. |
|
I cannot follow the decision not to support matrix parameters. Matrix parameters are used in JAX-RS, so they can be used in any Java Enterprise environment. Java is holding much more than 50 % of the enterprise market, i.e. any serious company out there is using it and not supporting it means to ignore this market. It's like summer without sun. Currently I have an issue with Swagger incorrectly rendering matrix parameters and the validation fails because of this. If swagger would at least ignore the parameters in this case it would be better. |
|
Anything new here? We really need to properly document our matrix parameters. Matrix parameters are mentioned as a common practice in the last paragraph of section 3.3 rfc-3986, although not formally specified as part of that rfc or named as matrix parameters. The original description of the concept is from Tim Berners-Lee from 1996.
What details do you have in mind? |
|
@webron agree, the offer was indeed for users above as a mean to overcome the current (and hopefully temporary) lack of support in swagger-ui.js |
|
👍 |
|
Well the patch seems to be relevant because Swagger's purpose is to describe REST API and indeed REST API/URI may have matrix parameters. So it is not that the patch is irrelevant IMHO but it is not ready to be applied due to the spec limitation. Would it make sense to release a 2.0.1 (or whatever the right version number is) patch spec and have a 'matrix' attribute ? Right now we are shipping an extension in CXF - and to be honest it is OK for us, but would be good to have it supported in the core spec. Cheers |
|
On the personal side - I cannot guarantee any issue becoming part of the spec in the future. There are very few issues I'm almost certain would end up in it, and this is not one of them. Swagger's purpose is indeed to describe REST APIs, but not all REST APIs. This has been discussed several times in the past, and I'd rather not open it up again in this thread. Having 2.0.1 with matrix param support is extremely unlikely. |
|
Well, thanks for being so specific about it. To be honest, as far as I'm concerned, it is not a massive deal, supporting matrix parameters, may be... But I'm puzzled by this resistance of the Swagger leads. I was under the impression Swagger was a flexible developer-driven movement open to the improvements (which are not based on someone's preferences but which can support a pretty basic URI attribute as in this case). Appears like it is a design by the committee. The language which can not reflect such a basic concept as a matrix parameter is limited. Consider revisiting a WADL design for the way the REST API description language can be designed. |
|
Following @sberyozkin, this is even more true if you consider that Swagger was chosen as basis for things like as the Open API Initiative |
|
@sberyozkin hang on. Please understand that swagger is extremely widely used, and if we just made spec changes willy-nilly, none of the tooling would work. What @webron is saying is that, yes, we want to support as many use cases as possible. But we cannot possibly support every framework's special syntax. I'm not saying that we won't be supporting the matrix syntax--in fact, it's not much different than adding another The OAI is going to consider all requests for spec changes here as we work on the next version of the spec. So your input is valuable. If you must support this now, please consider using an extension and adding support in a fork of the javascript library. Doing what you are describing is actually quite simple to implement. |
|
" But we cannot possibly support every framework's special syntax" - I hope you appreciate it is not a CXF or JAX-RS or Java specific concept, clearly a matrix parameter is a generic HTTP URI concept referring to an optional path segment attribute. |
|
I hate repeating this as it feels like beating on a dead horse. This is a spec, whether a formal one or not. We cannot make changes to the spec for everything that's 'non breaking'. Honestly, I wish it were that easy, but it's not. For every user that wants the change, there's another user who'd frown upon it (for a whole set of various and valid reasons). This is not us not wanting to add support, this is us trying to keep everything in balance. I hope you can appreciate we have a broad view of our users, tools, use cases and so on, and we try to take as much as we can into account. Now, just because something is a generic HTTP URI concept, does not mean we can or want to support it. Swagger is not WADL. Swagger does not aim to be WADL. While you may be using Matrix params, that still does not mean they are common. The claim @fehguy is making that other than JAX-RS we've yet to see a framework that supports it natively. There may have been mentions in the thread about other frameworks, I honestly don't recall, but for the current version of Swagger it does not matter, unfortunately. Mind you, the support for matrix params has been discussed in the 2.0 work group and was decided to be dropped. There wasn't enough conviction to make it happen. I'm happy to see that people are enthusiastic about it here and now because that does mean it will get the proper voice in the next iteration that may have been missing in the previous round. I'll sum it up by saying that there are a few open tickets that ask us to expand support of RFC 6570 in general, and in that sense, matrix param support falls under that as well. I do believe (can't promise) that we will indeed expand such support and that matrix params could easily be part of that as well. For reference here are the relevant issues: #291, #93, #394. |
|
Link to parent #565 |
|
Alternative parent issue: #574. |
|
Just another +1 to support Matrix parameters. |
|
+1 here, we use matrix params and can't find an easy way to document them...help! |
|
It is not hard to bolt this on, and that is probably why there is low framework support. As a regex with named groups on a path segment is all you need, this way you can easily validate complex matrix params and extract the values of the supported keys. Having regexes on path segments is extremely well supported. They are more widely used than you give them credit for, especially hidden usage through ways like explained above. I can imagine that you would not want to add every seldomly used technique out there but there is enough substance and standardization here to take notice and make this happen. See: medialize/URI.js#181
And citation:
Citation found under this angular url:
We as an industry are moving to more RESTful api's every day and it is obvious to me why matrix parameters are here and are making a comeback. I can also see that for now it is an advanced (REST purist) use-case which is why I understand that most frameworks have not implemented it yet. Also the DIY version of doing this without a specific framework implementation is dead simple, through regex path segments. Even if it were hard, most frameworks focus on the everyday use-cases for as long as possible to stay lean and relevant. However for api spec tools there truly is a market big enough that you should consider to cater for. |
Considering Angular 2 does not make the slightest effort to follow established standards and could not care less about interoperability, I do not see Angular 2 usage as a compelling reason to add support for any feature to any standard ever. |
It seems to be en-vogue to pick singular aspects out of context to then bash them. Closing an open discussion and refusing to understand that there are people that have views that do not match your own is IMHO what makes things un-great again. I actually wonder, what you are afraid of? Why is a feature that many people do consider useful not worth to reflect on? I do understand that feature bloat has to be avoided, but given that OpenAPI tries to become an widely accepted standard, shouldn't a widely perceived requirement be adopted, too? The ability to embrace diversity is what makes you strong. |
|
I already tried to address this issue to smartbear, just to put attention on the demand for matrix parameter support. Their paid tools, on the other hand, seem to support them - from what I saw in a demo. Simple question: is it kept out due to financial/commercial reasons? |
|
@xasx: "Simple question: is it kept out due to financial/commercial reasons?" please give me a break. Read the back log if you want the reasons why we're not patching the 2.0.x version. We're considering all aspects for 3.0 and honing in. There are other issues open tracking it. |
|
@xasx - I'll also reiterate since similar suggestions have been raised before in other forums - the people who drive the spec are six individuals who work as a team under a group called the TDC. Those six individuals do not represent the companies they work for, and even if they switch companies (and some have), the position stays with them regardless of the company they work for. Granted, we all bring our experience to the table, which can be affected by the place of work, but that's not what drives any of us to do the work. In fact, most companies who are members of the OAI don't even have representation in the TDC and have to submit tickets just like everyone else for changes to be considered. I'll even add and say that so far, we've added support for features that we think people should never ever use for new APIs and are there mostly to support description of existing APIs. We're aware that people will still end up using those for new APIs, unfortunately, and there's nothing we can do about that. This is not necessarily about what we think is right. We're not going to comply with all feature requests. Sometimes the reasons would be more sound, sometimes they'll feel arbitrary. We're not going to make everyone happy. Suggesting that we, the TDC members as a team, are driven by financial/commercial reasons (hinting towards the company we work fork), is not only wrong but is also offensive. We bring different aspects to the table, we disagree on plenty of things, and we end up finding the common ground. That's my essay for this time. p.s. |
|
@fehguy @darrelmiller @webron Thank you very much for your answers. I honestly appreciate your statements regarding my question 💟
I admit that the question was offensive, please don't take it too personally. It fulfilled its purpose of at least getting a statement from the important people behind OAI.
This statement was so missing in the backlog of this issue. People shouting for Matrix parameter support here get the impression that the idea of 'having an aspect in something because of people' is less worth than 'doing things because':
or
As for the other side: |
|
This has been added by #804 |
and others
Matrix type parameters are not fully supported by Swagger. Would be great to have them supported.
See following google groups discussion on this topic with concrete example and a bunch of links about what matrix parameters are:
https://groups.google.com/forum/#!topic/swagger-swaggersocket/lnQOLOLh3MI
Thanks for great product!
Greetings from Ireland
The text was updated successfully, but these errors were encountered: