add tags and path sorting, add related docs #3300
Conversation
There was a problem hiding this comment.
I do like this solution more than #2237 think realying heavily on swagger-ui is a good idea, on the other hand redoc not having this feature is a bit limiting so having it on our side could be nice? Personally never used redoc so this solution fits me more.
|
|
||
| ### Add Tags | ||
|
|
||
| You can group path by tags in both docs and redoc by using tags, tags also allows you to put descriptions and links. Tags description suppports markdown. |
There was a problem hiding this comment.
We already have docs about tags here: https://fastapi.tiangolo.com/tutorial/path-operation-configuration/?h=tags#tags and here https://fastapi.tiangolo.com/tutorial/metadata/?h=tags#use-your-tags
So don't see a use for this?
There was a problem hiding this comment.
Well I must have missed the second one, and the first one uses a slightly different way of defining tags;
Seeing this, I think the part about Tags sorting could be added to https://fastapi.tiangolo.com/tutorial/metadata/?h=tags#order-of-tags which is immediately after the second link you gave.
Also in the extending openapi doc we need to have tags defined so maybe we can just skip the Add Tags and instead put a link toward the doc here https://fastapi.tiangolo.com/tutorial/metadata/#metadata-for-tags
Let me know what you think so I can rewrite this part of the doc.
There was a problem hiding this comment.
I like adding it to https://fastapi.tiangolo.com/tutorial/metadata/?h=tags#order-of-tags, the https://fastapi.tiangolo.com/tutorial/metadata/#metadata-for-tags seems like a different thing?
There was a problem hiding this comment.
Hi, I included in the doc (metadata/order of tags) a link to the extending-openapi doc. metadata for tags is a bit different as it is the customization of the tags headers with markdown description and url link
|
|
||
| It is good to have a documentation, but a sorted one is better, you can use tags_sorter and operations_sorter to sort your docs. | ||
| See this thread for the underlying logic (Swagger UI 3.17.6 required, Redoc not affected) : | ||
| <a href="https://github.com/swagger-api/swagger-ui/issues/2990" class="external-link" target="_blank">https://github.com/swagger-api/swagger-ui/issues/2990</a> |
There was a problem hiding this comment.
Is there a doc where all of them are listed? Dislike the fact it's linking to an issue, couldn't figure out the complete list myself.
There was a problem hiding this comment.
There is a doc here https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/ but it is very general and options are listed along a lot of other. Maybe it is possible to put direct link or highlight...
There was a problem hiding this comment.
Considering it's not in a separate table I doubt you could make a good highlight, think it's still better link than github issue, just need a way to point to the correct variables
There was a problem hiding this comment.
I included the link to this general swagger doc and put as a technical note the link to the issue describing the technical implementation
| ``` | ||
|
|
||
| !!! tip | ||
| Possible values are "aplha" or a custom build *sort* function for the tags, |
There was a problem hiding this comment.
A example method for "sort" would be 👍
There was a problem hiding this comment.
The Swagger UI link back to https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort
but yes I think I could manage to create a custom sort function as an example. Something like elt1.length> elt2.length could be kinda visual I think
There was a problem hiding this comment.
Doesn't need to be that visual, just changing around 1 endpoint would be enough.
There was a problem hiding this comment.
I wrote a function in a generic manner using the length as ordering as it is simple to understand, effectively changes the display order in a easy to check way and as a bonus it allows to show the way of getting each entry "name" which is the operation path.
operations_sorter='function(e,t) {\
if (e.get("path").length < t.get("path").length) {return -1;}\
if (e.get("path").length > t.get("path").length) {return 1;}\
return 0;\
}',
…tom function execution
|
So I put together the doc changes we talked about and made a small implementation tweak to allow custom function execution along with the custom function example. I am not quite happy with this version cause it force people to use '"alpha"' instead of "alpha" (mind the quotes). Maybe we could do a test on whether it's alpha/method and put quotes in those cases; although this would imply updating tests if SwaggerUI adds more ordering. |
|
@tiangolo can I hope this to be merged anytime soon ? Or is there anything to change in the proposed code, or the proposed doc update ? |
|
|
||
| It is good to have a documentation, but a sorted one is better, you can use tags_sorter and operations_sorter to sort your docs. | ||
|
|
||
| Possible values are "aplha" or a custom build *sort* function for the tags, and "alpha", "method" or a custom build *sort* function for the operations as defined in the <a href="https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/" class="external-link" target="_blank">Swagger UI doc</a>. |
|
Hi, this functionality has been implemented as part of #2568 under the swagger_ui_parameters so it is no longer needed, I'm closing to keep thing clean, thank you all |
Hi, having the need to sort the swagger documentation, I made a quick changes that resolves : #1000
It relies on swagger-api/swagger-ui#2990 for the underlying sort operation.
It might be a duplicate functionality regarding #2337 but the way it works is way simpler as it relies heavily on swagger to do the work.
I also checked for Redoc ordering but reading Redocly/redoc#98 it seems it is not done yet.
Please let me know if some changes are needed before you can merge, thanks for your work @tiangolo