Sorting operations by operationId should be configurable

[malinthaprasan]

Description

DefaultGenerator sorts all operations by operationId when generating. That becomes a problem when generating documentation because non important operations can come to the top of the generated documentation. I think this need to be decided by the user/developer so that need to be configurable. If the developer not willing to sort, the order of the operation should be the order they specify in the swagger.

Please see below code snippet that causes the problem. https://github.com/swagger-api/swagger-codegen/blob/v2.1.6/modules/swagger-codegen/src/main/java/io/swagger/codegen/DefaultGenerator.java#L353

Collections.sort(ops, new Comparator<CodegenOperation>() {
    @Override
    public int compare(CodegenOperation one, CodegenOperation another) {
       return ObjectUtils.compare(one.operationId, another.operationId);
    }
});

Swagger-codegen version

2.1.6

Swagger declaration file content or url

swagger: "2.0"
info:
  version: "1.0.0"
  title: "Swagger Petstore"
paths:
  /pet:
    get:
      tags:
      - "pet"
      summary: "Add a new pet to the store"
      description: ""
      operationId: "veryImportantPetOperation"
      responses:
        200:
          description: "OK"
  /pet/findByTags:
    get:
      tags:
      - "pet"
      summary: "Finds Pets by tags"
      description: ""
      operationId: "notImportantPetOperation"
      responses:
        200:
          description: "successful operation"

Command line used for generation

java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate -i sample.yaml -l dynamic-html -o samples/sampleHtml

Steps to reproduce

1. Build the swagger-codegen source from v2.1.6 tag.
2. Create a yaml with above swagger content.
3. Generate dynamic-html doc
4. Navigate to samples/sampleHtml
5. npm install
6. node .
7. goto http://localhost:8002 and see docs.

Observation: Although veryImportantPetOperation is defined in the top of the swagger doc, it has become the last in the generated html docs.

Related issues

https://github.com/swagger-api/swagger-codegen/issues/193

Suggest a Fix

The sorting need to be configurable with a true/false value. If it is false, we should keep the order we specified in the swagger document. We might be able follow https://github.com/swagger-api/swagger-codegen/pull/1272 for this issue as well.

[wing328]

@malinthaprasan the suggestion sounds reasonable to me.

Do you have cycle to implement the CLI option to make the sorting configurable?

Btw, we've released stable version 2.2.0.

[atdiff]

Any update on this or timeline when it might happen?

[hn3000]

We'd like to have the same thing for our documentation.

Looking through the code I found the class Path that has a separate member for each HTTP verb. This means that the order of "get" / "post" / "put" etc. is not remembered from the input file.

Regarding community contribution -- would you be open to changes to this representation as well?

[fehguy]

seems like a reasonable thing to do

[mkistler]

I would also like an option to generate operations in the same order as they appear in the swagger doc. But I think this problem is far more complicated than just adding a cli options to bypass sort operation shown in the comment above.

The source of all the information about operations comes from the Swagger object returned by the swagger parser -- specifically the getPaths() method, which returns a Map<String, Path>. In general, a Java Map does not guarantee any ordering of its keySet(), so the plain fact is that the swagger object does not preserve (in its public API) the order that operations appear in the swagger document.

So any true fix must necessarily involve changes to swagger-core, to provide some property that captures the order of paths/operations, and swagger-cli, to collect and then persist this ordering information in a Swagger object. Only then can changes in swagger-codegen be undertaken to use this information to order operations consistent with the ordering in the swagger doc.

I'm relatively confident in my analysis but would be happy for anyone to offer a solution for ordering of operations by appearance in the swagger doc without changes to swagger-core and swagger-cli.

[fehguy]

Swagger-core uses linked hash maps, which are ordered by design.

[mkistler]

That's true, but the property is exposed as simply a Map, which provides no ordering guarantee. This is why I added the qualification "(in its public API)" above. So one approach to fixing this is to change getPaths() to return a LinkedHashMap whose elements are in the order of appearance in the swagger doc.

But this isn't enough, because swagger-core allows paths to be set with setPaths() that accepts a map -- any Map, not necessarily a LinkedHashMap. And indeed, swagger-parser uses this method and passes a mere HashMap of paths, not a LinkedHashMap, which again does not preserve order. So to fix this, the swagger-core setPaths() should be changed to require a LinkedHashMap and then swagger-parser should be changed accordingly.

[hn3000]

In addition, the Map<String, Path> contains objects that do not (and can not) store the order of declarations:

https://github.com/swagger-api/swagger-core/blob/5ba1f72116383085dbc4d0820ce19afc63bb0a28/modules/swagger-models/src/main/java/io/swagger/models/Path.java#L15-L21

So even if that map keeps the ordering (which it does, at the moment), the order of the http verbs will be the one hardcoded here:

https://github.com/swagger-api/swagger-codegen/blob/master/modules/swagger-codegen/src/main/java/io/swagger/codegen/DefaultGenerator.java#L727-L733

Or are there more recent versions of these I should be looking at?

[Way2nnadi]

Was a fix ever put in for this issue?

[cyphercodes96]

I've been having issue's, using swagger-codegen-cli v2.2.3, where i'm referencing a swagger.json file, whose params are not consistent and changing constantly on each server. However, the SDK generator should FIX my PARAMETER ORDER ONCE AND FOR ALL. Each and every time i regenerate the SDK, I have to go through all my application used requests, and verify that the param order is still valid, and if not, I have to fix it.

Any help upon this issue once so ever?!