swagger-api / swagger-api/swagger-codegen

Sorting operations by operationId should be configurable

Open
#3,485 10 comments 6 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Enhancement: Feature help wanted
Dominant language
Mustache
Stars
17.8k
Forks
6k
PR merge metrics
No merged PRs in 30d

Description

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.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start in modules/swagger-codegen/src/main/java/io/swagger/codegen/DefaultGenerator.java around line 353 and review the related issue 193 and pull request 1272 for existing context. The change is complete when sorting by operationId can be configured and disabling it preserves the order defined in the Swagger document.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
documentation, tooling
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.