swagger-api / swagger-api/swagger-codegen
Sorting operations by operationId should be configurable
Nobody has claimed this yet.
- 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
- Build the swagger-codegen source from v2.1.6 tag.
- Create a yaml with above swagger content.
- Generate dynamic-html doc
- Navigate to samples/sampleHtml
- npm install
- node .
- 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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