Redoc: Feature Request: Navigation Sorting

[gmr]

I just saw this tonight and have already started to roll it out for my APIs.

One nit is the ordering of the sidebar navigation seems to be fairly random.

It'd be awesome if I could sort endpoints in the navigation with an x- variable or by setting a configuration value that told it to sort alpha by operationId or summary.

[RomanHotsiy]

already started to roll out

👍 🎉

Currently, methods are grouped by tags (similar to the SwaggerUI) and tags (top level menu items) are sorted according to the order of tags field.

Inside tags methods are ordered in the same order as the appear in json/yaml spec (yes I know json doesn't have an order but in all modern javascript engines it appears to have 😄 )

If you have many endpoints - tags are a good way to organize things.
If this doesn't work for you, we can discuss some option or x- vendor extension.

[gmr]

I have the tags for organizing, I was more interested in the actual endpoint/method sorting. I've also noticed request and response parameter sorting doesn't match the spec as well.

It seems the sorting is deterministic, but not based upon the document as far as I can tell.

I was thinking an x-sort-order or something might be a good way to go, but perhaps I'm missing something.

Thanks BTW, this is exactly what I was looking for when I started this.

[jonyw4]

I need this feature too. How I can support? +1

[slavcodev]

I'm interesting in the order of side menu too. And this is my proposal.

The headers from the info description are rendering as menu items now. Also ReDoc already supports kind of "widgets system" using HTML comment for the injection of the security definitions. I propose to use these features further. There is example how to inject operations in the info description:

~~~yaml
info:
description: |
# Introduction
...
# Group e.g. Pet

## Add a new pet to the store
<!-- see: #/paths/~1pet/post -->

## Update an existing pet
<!-- see: #/paths/~1pet/put -->

tags:

• name: Pet
  description: Everything about your Pets
• name: Store
  description: Access to Petstore orders
  paths:
  /pet:
  post:
  tags:
  - pet
  summary: Add a new pet to the store
  put:
  tags:
  - pet
  summary: Update an existing pet
  ~~~

The conventional rules:

1) The operation summary should be same as the header title.
2) The operations missing from info will be rendered by usual in menu item by tag.
3) If header title coincides with tag name, tag description will be injected in info

And optional, ReDoc can support different header levels for operations, in order to extended group ing. E.q.

~~~yaml
info:
description: |
# Introduction
...
# Group

## Sub-group
<!-- see: #/paths/~1pet/post -->
### Add a new pet to the store

## Sub-group
### Update an existing pet
<!-- see: #/paths/~1pet/put -->

~~~

[fenollp]

We'd also would love to have this as an option. Maybe --options.sortNavigationTags=true?

[AndriiMz]

@fenollp @RomanHotsiy

added made some changes locally and added "sortNavigationTags" option:

tests passed, can we discuss and make a or with such feature? it's we important for our team.

[adamaltman]

FYI: they are sorted by the order they are defined in paths now in the root definition file.