Accordions?

[dagnelies]

Hi,

First, thanks for this theme 👍

Once the API grows a bit, it becomes a large list of operations, which is "uncomfortable" to navigate quickly.

IMHO it would be nice to tag sections expandable/collapsible (like swagger ui for example). This would make navigation much more easy.

[GrahamTheCoder]

Yep great work, but I have the same issue. Perhaps a left hand navigation like this (and others) use would be good: http://swaggerui.herokuapp.com/

[mrin9]

Wanted to share an update on this issue:

• First, the suggestion made by @GrahamTheCoder. That option won't work for RapiDoc as the left navigation is created out of path-summaries which is an optional field as per OpenAPI spec, moreover they can contain markdown syntax. So we will continue the use of path to explore the spec
  You can try out the above app with BitBuckets API spec https://rapidocweb.com/specs/bitbucket.json and find that the menu system isnt working as expected.
  Same is the case with Redoc's menu system https://redocly.github.io/redoc/?url=https://rapidocweb.com/specs/bitbucket.json#tag/addon

• Second, We did some survey about this on how to make things more easier to navigate for a large spec, the most important thing that we hear is to reduce the path clutter when the spec is large, so we will be attempting at generating a list of unique paths. That is, say, if there are multiple methods GET PUT POST DELETE etc for the same path then it will be listed only once. In our current implementation it list multiple times

It is still at an initial stages of design and we do not know when in the feature it might make it to the product.

[mrin9]

release 5.3.0 now has the option to endpoints by path
check it out in action at https://rapidocweb.com/examples/group-by-path.html

you are welcome to provide feedback

[StephenNay]

I realize that this issue is closed, but I thought I'd provide some of that feedback that you asked for.

First, I think it's pretty slick to be able to view the API by tag or by path. I have some comments, based on my role as a writer and information designer:

• In the "path" view, putting the paths on the left and the methods on the right isn't optimal because it's too far for the eye to travel, unless you are looking at a very narrow window.
• The "path" view hides any description/summary about the purpose of anything. Many people aren't good at naming things, or what's obvious to one person is not at all obvious to someone else, so it's a big step of faith to assume that the words in the URLs are going to be enough.
• When you click on a method in the "path" view, the expanded section shows both the summary and the description, which is pretty redundant. Hmm, I see that that's true in the "tag" view, too. The summary is really nice in the "tag" view, but the expanded view doesn't need both. I should open a separate issue about that.
• I think the "path" view would be most appreciated by someone who is already very familiar with an API and who knows what they are looking for and just needs the details of some specific request. Swagger UI is the same way. Neither one is great for someone who is not familiar with an API and needs to see more clues about what the resources are and what the requests do. For that, the "tag" view is better, assuming that whoever created the Swagger/OpenAPI definition took time to include some descriptions.

I'm going to agree with @dagnelies original suggestion that some form of vertical expanding/collapsing would provide a better user experience for larger APIs. The "path" view has value, but it's not the equivalent of expand/collapse. One of the limitations of Swagger UI is poor navigation, and expanding/collapsing sections is a huge help in tools that provide that.

Granted that the left navigation in "tag" view is based on optional fields, but I think it's okay to say that RapiDoc produces better and more useful output when the source material contains more information. If a method doesn't have a tag, RapiDoc could put that in an "Other" section. RapiDoc doesn't create information -- it just makes it pretty. :-)

You said that fields used to create the left-column navigation can contain Markdown, but I don't think that's true for just tag names, is it? I think those can only be text. It's the tag descriptions that can contain Markdown.

[dagnelies]

I agree with @StephenNay ...it's not optimal on the right.

IMHO, I would place the HTTP Verbs in a fixed size column on the left, like this:

------------------------------------------------------------------------------
                             GET     /whatever
-------------------------------------------------------------------------------
                 GET POST DELETE     /whatever2
-------------------------------------------------------------------------------
     .....

...most of us developers working with REST APIs often do so on desktops with big screens and not on smartphones. Therefore, IMHO taking up some space should not be an issue.

what I think might further slightly improve readability is to highlight the last part of the path, like this:

/resource
/resource/{id}/subresource
/resource/{id}/subresource/{whatever}/thingy1
/resource/{id}/subresource/{whatever}/thingy2
...
/other

[mrin9]

sorry about commenting late on this, I missed the comments since the issue was in closed state.
but for anyone visiting this thread in future.

The "Group By Path" option introduced in 5.3.0 have been removed as we received poor user feedback on that. Instead we now present a two rendering styles view and read