As i need to keep all versions in a single doc, Happy to be told that header accept version can be documented in a different manner, We need this feature too. https://unpkg.com/swagger-ui-plugin-hierarchical-tags. Sign in This is what it looks like so far: I tried left-justifying, too, but that made the hierarchy significantly less useful. @mathis-m, I know you commented above that it was not possible to integrate the styling that you devised into the plugin. Below is a full working To the devs: I repeat my offer to implement this and PR it if you'll give me a push to start me in the right direction ;). If anyone's a whiz with this kind of stuff (css, react, etc. Corporate frowns on unofficial versions of major software but plug-ins are fair game! I can give you guidance, let's connect to get this going! I just looked at the code and with the knowledge of the swagger ui system from back then I think this because of this lines of code:https://github.com/kael-shipman/swagger-ui-plugins/blob/hierarchical-tags/packages/hierarchical-tags/src/HierarchicalOperations.jsx#L79-L98. I would be happy to see if I can at least get the plugin styled up nicely and then we can just let it be. Already on GitHub? When test1 and test2 ends on "Second Tag" and test3 ends on "Third Tag" then UI is OK. @kael-shipman @Randerspl Hi guys! hmm it takes a while, but looks like it's on npm now (https://www.npmjs.com/package/swagger-ui-plugin-hierarchical-tags). Alright folks, I believe I've just successfully published the package. For example, Swagger UI usestagsto group the displayed operations. In case that a nested tag at any level already exists, like in your example tag1 and tag2. Sent from a mobile phone please excuse the brevity of the comment. In addition specification wise we are good to implement it. to your account. Gotcha gotcha, yea that would be super helpful as I could then easily use it as a script in my docs.html. But in case there are hirachical tags that end on different levels there is a issue. Any updates if (or when) this feature is merged into swagger-ui? At least in the APIs I work with, this could still be very long. However. the PR is now years old. So, uh, no options for anyone using .net's Swashbuckle? Tagged operations may be handled differently by tools and libraries. Very helpful. Hm. No, unfortunately the unpkg.com links only work for packages published on npmjs.com. I just tried exactly what you said in your bug report and I got the expected results - see screenshots below. Additionally, you have to prefix the package name with @kael-shipman. @kael-shipman I was trying to get it to work, but unsuccessful so far. I've never really used nest, so wouldn't know how to integrate a plugin. Since I've got a PR out for this plugin to be included in the repo owner's "official" set of plugins, I chose not to publish the package on npmjs.com. I would like to implement it in SwaggerUI and would like help identifying the best way to do so. privacy statement. I think sub or hierarchical tags would make life so much easier for developers and readers of the docs. Hmm. @Randerspl I'm afraid I'm not able to replicate this. Is it available as a plug-in I can just drop in. My use case is, I have an existing API with 2 versions, about to start on the third, consumers add a field in the header asking for specified version. Was also running into the same issue when trying to require the package as stated in the README. The taggedOperations selector of swagger-ui returns a map to a datastructure containing information about the tag itself and about its operations. Hi to everyone following this. It would be really helpful to be able to add sub headings and also even a description to each sub heading so you could explain the purpose of the grouping, @kael-shipman you could probably just override the component https://github.com/swagger-api/swagger-ui/blob/master/src/core/components/operation-tag.jsx using the plugin api. You can get it by doing the following: I believe that will work, but if it doesn't, I'd be happy to work through it with you. then had to figure out how to actually login in npmjs and generate a token on github but finally it all worked. This would be great! fix: oauth2 not defined by exports - ONE LINE CHANGE. Use it to register the plugin. The doc would be much more organized for the front end folks of my project. You signed in with another tab or window. This should work! Yes, would be great to have such a feature! (optional) special delimiter characters to denote hierarchy. Having tag names with | (pipe) symbols in them causes connexion to create modules with names which are unimportable, https://github.com/swagger-api/swagger-ui/blob/master/src/core/components/operation-tag.jsx, https://swagger.io/docs/open-source-tools/swagger-ui/customization/plugin-api/, kael-shipman/swagger-ui-plugins@hierarchical-tags, https://github.com/kael-shipman/swagger-ui-plugins/tree/hierarchical-tags/packages/hierarchical-tags, https://unpkg.com/swagger-ui-plugin-hierarchical-tags, https://www.npmjs.com/package/swagger-ui-plugin-hierarchical-tags, https://email@example.com, https://github.com/kael-shipman/swagger-ui-plugins/blob/hierarchical-tags/packages/hierarchical-tags/src/HierarchicalOperations.jsx#L79-L98, Fix hierarchical tags structure generation, Create a github personal access token for your account (. If you (or anyone else) know how to get us over this hump, I'd be more than happy to give you publish permissions on the npm package. Overflow problem in response-inner div solved. I just got back from vacation - and also am recovering from covid :( :( - so I won't be able to look into this right away, but I'll try to fix it this weekend. Here are the instructions, copied for convenience: (Note that, while this package will remain available ad infinitum, this should be considered a temporary solution until swagger gets around to reviewing our PR and integrating this feature into their core codebase. By clicking Sign up for GitHub, you agree to our terms of service and The current consensus is that UIs like SwaggerUI can implement this with no change required in the OAS, and that this would be a much appreciated feature. @tim-lai, @mathis-m and I are working on a PR to swagger-ui to address this issue and we've run into some questions: First, are you interested in this being part of swagger-ui? I wrote similar but simpler http server that i used when i had problem and generated swagger json with replication of problem.
html document that you can use as a starting point: npm i swagger-ui-plugin-hierarchical-tags, github.com/kael-shipman/swagger-ui-plugins/tree/hierarchical-tags, https://unpkg.com/swagger-ui-dist/swagger-ui-bundle.js, , https://unpkg.com/swagger-ui-plugin-hierarchical-tags, https://unpkg.com/swagger-ui-dist/swagger-ui.css, "https://unpkg.com/swagger-ui-plugin-hierarchical-tags/example/pet-store.json". There is growing support in the OAS community for the idea of hierarchical tags (see OAI/OpenAPI-Specification#1367). I am also looking for the same thing. Next on my list is css colors to brand it for my company that should be interesting. Will go a long way to making my swagger page as user friendly as possible. Im using tags with spaces, maybe this is a problem? When test3 endpoint ends on "Second Tag" then is missing The text was updated successfully, but these errors were encountered: I'm willing and able to implement this, even if just for my own fork of SwaggerUI, so regardless of whether this feature gets official approval or not, I'd love for someone to give me a hint at where to start.
I'm a bit swamped at work right now, but I'll look into maybe building a plug-in for this when I get a chance. And then a tag follows that ends at at a already tracked tag level like first level or second level, nothing will be done. I'm using the docs.html approach in order to load up the swagger-ui. You signed in with another tab or window.
Swagger UI should work without Node.js polyfills - rewrite generateCodeVerifier to avoid transitive dependency on Buffer (Node.js API), feat: re-retch schema, when authorization is changed #7425, Enable running with a read-only filesystem, feat(try-it-out): validation should consider readOnly, refactor: replace randombytes with native methods, embrace users employing swagger for model-only specifications; don't , Fixes #5850 performance issue request body editor, Feature: Introduce additional form params (#5399). Delimiter characters are | and :. Lemme know if it doesn't. @monirul017 mmm, I don't know. To be honest, I'm fairly new to swagger myself. @mathis-m thanks for the specific tip and documentation! Is this link still working for the script? Sign up for a free GitHub account to open an issue and contact its maintainers and the community. Good to know others find this desirable. Thanks for commenting! Any thoughts on styling? I found some minutes for a minor investigation. @Edweezu sorry, it looks like I updated the docs on my self-hosted branch here, but not on the branch that I've got a PR out for. I'm a novice but willing to try it . I've also updated the readme at https://github.com/kael-shipman/swagger-ui-plugins/tree/hierarchical-tags/packages/hierarchical-tags, so instructions there should yield a successful deployment. If not, we can stick to the plugin approach already mentioned above. https://swagger.io/docs/open-source-tools/swagger-ui/customization/plugin-api/. EDIT: If you don't already have github authentication set up for npm, you have to do that as well: @kael-shipman let's make this a PR against swagger-ui. I've implemented it as a backward-compatible core addition in this branch, but @mathis-m has suggested it may be more appropriate to build it as a core plugin, which he's started working on in this branch. I published a version to npm at v1.0.0-rc1, but it doesn't seem to show up on unpkg. Can you be more specific about the problem? I have it working. Thank you both for your patience with me. Doesn't seem like it's building properly tho (https://firstname.lastname@example.org). Yes, as indicated in my answer above, the package is hosted on github, so you have to add my repo to your .npmrc file (I prefer project-local .npmrc files because then the configuration sticks with the repo and it becomes transparent to all other devs, but you can also put it in your global ~/.npmrc file). Now when i wrote smaller service i think i found a proper replication. Next, require it in your client-side application: You can also quickly and easily direct-link the file using unpkg.com. then implement recursive rendering of the operation-tag within the render function of the component. So operations on the same level will work with the current plugin logic. Second, if it seems acceptable for swagger-ui, what is your preferred architecture? It'd be nice to have some kind of vertical gray line on the left to signify how deeply something is nested. Have a question about this project? What the plugin tries to do is to create a nested map by splitting the tags at a delimiter. I did what you told me to do.It says i am unauthorized or entered incorrect/missing password. Let me know if it doesn't work. Aha, thanks, @Randerspl , for the bug report. Unable to require it in my client side app & apply to Swagger instance as I'm working w/ this in the backend. On first attempt endpoints were shown properly in GUI (all tags were ending on "Third Tag"), but when i changed one endpoint to end on "Second Tag" then this endpoint disappeared from GUI. I desperately need this functionality now. Can you post a swagger.json file that correctly replicates the problem? I have to say, I'm totally new to this area of of front-end development. It'd be awesome to have such feature available - as of now, I need to create composed tags which causes lots of duplicates. ), totally glossed over those steps then had to figure out what tehy meant. Our API serves several products but also we have utility endpoints, global endpoints and product specific endpoints.
Tags such as Petstore|Mammals|Dogs should render as. Lemme know. And probably also add the tag information if available. ), feel free to PR my PR over at kael-shipman/swagger-ui-plugins@hierarchical-tags. This is shown ok in swagger UI, but endpoints 1 and 2 just disappeared. The three endpoints as described originally: The endpoints after changing endpoint 2 to have a further level of hierarchy: Hello, sorry for long time for response @kael-shipman. Maybe i was wrong in describing, because on what i worked had more than 3 endpoints and maybe i interpreted wrongly source of a problem. I would say your best bet would be to use it in plugin form. Perhaps I'll go ahead and just publish it. @dmrickey Yea sure have a look at using your own index.html. If you ever make the plugin have the additional bars that would make it look even better but the indented subsets are a nice add. Instead the logic should combine the operations on this level with the ones of the current tag. Open to suggestions. @kael-shipman for the plugin part I would use the wrapComponents plug point to conditional render either the hirachical operation tag component or the original component. The original (draft) PR is now WAY behind the main branch and neither I nor @mathis-m seem to have much time or energy to push it through. Haha yes, this stuff gets awfully deep. Let us know if you get stuck again. Hey @kael-shipman, Great plugin! I can't seem to get it to work. I think either way is fine for us, but we'd like guidance before investing too much in one direction or the other. Well occasionally send you account related emails. Read through those docs and lemme know if you can't get it to work. Also, if anyone's really itchin' to get this going on their site, I just published the pre-release (v1.0.0-rc1) on github packages. When I publish docs, I usually use redoc, although the reason I started this thread to begin with was because they didn't have hierarchical tags either (and still don't). Does your script approach (https://github.com/kael-shipman/swagger-ui-plugins/tree/hierarchical-tags/packages/hierarchical-tags) still work? This plugin produces a layout with endpoints grouped into a hierarhical list based on tags with @ASchwad unfortunately I think we're a little stalled out here. changes for select option and login api call. Im using akka-http and swagger-akka-http for json file generation (that's why Function1RequestContextFutureRouteResult scheme exists) and then i just serve web-jar swagger-ui (version 4.10.3) in server and use generated swagger.json on page. For example i have 3 endpoints: Now for better grouping i changed endpoint 2 to have another sub tag for example to this: Tag1|SubTag1|SubSubTag1. now I'll do the redme.md part again. I will try to provide PR when I get home later today. Something makes me think it should be possible, though. @kael-shipman @mathis-m Great work! When test3 endpoint ends on "Third Tag" then its OK. Great tool @kael-shipman and its working great for me, but i think i found a small bug and i don't know where to report it so i say it here. chore(deps-dev): bump postcss-loader from 6.2.1 to 7.0.1, Add support to refresh token automatically. It looks like adding new level just removed previous level entries (they still are in my swagger.json file). Ah, you need to set up authentication with github: @kael-shipman I am trying to use it with nest js application is there any way to use it with nest js?