Sort API methods in Swagger-UI

Question

I cannot find any working example, how to achieve the following: I want my API methods in the Swagger-UI sorted either by methods (GET-POST-PUT-DELETE) OR/AND alphabetically.

So far, all methods are displayed in a random order, even not in the order given my source code.

I use Jax-RS + Jersey 1.

Sorting using the position attribute of @ApiOperation is not an option for me, as there are too many methods and the API is still extending, so I would need to update all if there is a new one.

Any hints?

Anthony Neace · Accepted Answer · 2015-09-02T14:17:07.790

Update for Swagger UI 2.1.0+: The sorter parameter has been split into two parameters, as noted in Fix 1040, Fix 1280:

apisSorter

Apply a sort to the API/tags list. It can be 'alpha' (sort by name) or a function (see Array.prototype.sort() to know how sort function works). Default is the order returned by the server unchanged.

operationsSorter

Apply a sort to the operation list of each API. It can be 'alpha' (sort by paths alphanumerically), 'method' (sort by HTTP method) or a function (see Array.prototype.sort() to know how sort function works). Default is the order returned by the server unchanged.

So you'll want to update sorter to apisSorter to sort the API list alphabetically, and/or operationsSorter to sort the operations list of each API. The pet shop demo has updated to apisSorter, as shown below:

Example: (working demo, sorted alphabetically)

window.swaggerUi = new SwaggerUi({

...

apisSorter : "alpha"
});

For Swagger UI versions older than 2.1.0:

The sorter parameter is still relevant for older versions of Swagger UI:

You can use the sorter parameter when instantiating SwaggerUi. This happens in the javascript on the Swagger-Ui index.html. From the documentation:

sorter apply a sort to the API list. It can be 'alpha' (sort paths alphanumerically) or 'method' (sort operations by HTTP method). Default is the order returned by the server unchanged.

Example:

window.swaggerUi = new SwaggerUi({

...

sorter : "alpha"
});

Thanks, that seems to be the solution I was looking for! Unfortunately I can't get it working, neither with 'alpha', nor 'method'. Migrated to Jersey-2 in the meantime, using swagger.js 2.0.30 and swagger-jersey2-jaxrs_2.10 1.3.4 now. Any idea, if that should be working with this configuration? — ulrich, Sep 25 '14 at 07:57
Ok, the sorter param seems to be quite new. I also updated my swagger docs to the ones from your link (swagger.js 2.0.41) and that works with the sorter parameter! Pretty cool:) — ulrich, Sep 25 '14 at 10:10
for tag sorting, it's `tagsSorter` now. `tagsSorter: "alpha"` — Robin C Samuel, Feb 17 '19 at 06:43

score 11 · Answer 2 · answered Sep 02 '15 at 05:10

11

The accepted answer is a bit outdated. In newer versions it is done by:

window.swaggerUi = new SwaggerUi({

...

apisSorter: "alpha", // can also be a function
operationsSorter : "method", // can also be 'alpha' or a function
});

answered Sep 02 '15 at 05:10

Kenyakorn Ketsombut

2,072
2
26
43

Thanks for that update! Could you add a hint, which version it refers to? – ulrich Sep 02 '15 at 06:18
Unfortunately I can only confirm that this works in version 2.1.1. That is currently online and I'm also using it like this. It is also documented here: https://github.com/swagger-api/swagger-ui/blob/master/README.md . But I can't say, when they changed it and since when the other one is outdated :( – Kenyakorn Ketsombut Sep 02 '15 at 07:48
1

for tag sorting, it's `tagsSorter` now. `tagsSorter: "alpha"` – Robin C Samuel Feb 17 '19 at 06:42

score 11 · Answer 3 · edited Sep 27 '21 at 10:59

11

I had the same issue and I fixed it like this

window.swaggerUi = new SwaggerUi({
    apisSorter: "alpha", 
    operationsSorter: function (a, b) { 
    var order = { 'get': '0', 'post': '1', 'put': '2', 'delete': '3' }; 
    return order[a.method].localeCompare(order[b.method]);    
  },
});

edited Sep 27 '21 at 10:59

ulrich

1,431
3
17
46

answered Sep 30 '15 at 19:56

Hiddenben

111
1
3

Which version do you use? Is this also 2.1? – ulrich Oct 02 '15 at 09:10

score 2 · Answer 4 · answered Nov 07 '19 at 09:36

Update for Swagger 3.18.3

 window.ui = SwaggerUIBundle({
           ...
            operationsSorter: function (a, b) {
                var order = {'get': '0', 'post': '1', 'put': '2', 'delete': '3'};
                return order[a.get("method")].localeCompare(order[b.get("method")]);
            },
           ...
 });

score 2 · Answer 5 · edited Nov 30 '22 at 14:34

2

Update for 3.x+

As also mentioned in comments previously, apisSorter seems to have been renamed to tagsSorter in v. 3.x, see Swagger configuration documentation.

window.ui = SwaggerUIBundle({
  ...
  tagsSorter: "alpha",
  operationsSorter: "alpha"
  ...
});

edited Nov 30 '22 at 14:34

Helen

87,344
17
243
314

answered Sep 23 '21 at 07:57

ulrich

1,431
3
17
46

score 1 · Answer 6 · answered Oct 11 '21 at 19:33

To sort api tags and operations in nestjs you can pass SwaggerCustomOptions to SwaggerModule.setup() method in following way:

import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';

//...

const config = new DocumentBuilder().addBearerAuth().build();
const document = SwaggerModule.createDocument(app, config);
SwaggerModule.setup('api/docs', app, document, {
  swaggerOptions: {
    apisSorter: 'alpha',
    tagsSorter: 'alpha',
    operationsSorter: 'alpha',
  },
});

May duplicate https://stackoverflow.com/questions/64974561/nestjs-alphabetize-endpoints-in-swaggerui — Sergey Kanygin, Oct 11 '21 at 19:35

score 0 · Answer 7 · answered Jun 30 '20 at 14:40

0

For .net Core users with SwaggerUI3:

 app.UseSwaggerUi3(j=>j.TagsSorter = "alpha");

answered Jun 30 '20 at 14:40

Shadi Alnamrouti

11,796
4
56
54

What about ordering the API methods where controller/method_name is not used in the route as `[HttpGet("{id}")]` and `[HttpGet]`? I tried this approach, but does not work. Any idea? – Jack Oct 08 '20 at 13:09

score 0 · Answer 8 · answered Aug 03 '21 at 13:00

For Python folks who end up here with the same issue, here's how to solve it

Using flasgger v0.9.5 (=Swagger-UI 3.28.0) and Flask v2.0.1:

app = Flask(__name__)
config = {
    "ui_params": {
        "operationsSorter": "alpha",  # sorts endpoints alphabetically within a tag
        "tagsSorter": "alpha". # sorts tags alphabetically
    }
}
Swagger(app, config=config)

score 0 · Answer 9 · answered Oct 05 '21 at 14:32

With my version of swagger i've managed to do like this:

apisSorter: "alpha", 
operationsSorter: function (a, b) { 
    var order = { 'get': '0', 'patch': '1', 'post': '2'};
    return order[a._root.entries[1][1]].localeCompare(order[b._root.entries[1][1]]);
}

Sort API methods in Swagger-UI

9 Answers9

Linked