OpenAPITools / OpenAPITools/openapi-generator

[REQ] Organise generated HTML doc by the yaml order, not alphabetically

Open
#12,950 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Enhancement: Feature
Dominant language
Java
Stars
26.8k
Forks
7.7k
PR merge metrics
PR metrics pending

Description

Is your feature request related to a problem? Please describe.

I use openapi-generator to generate static html documentation of API.
The list of endpoints is organized using the tags in a ascending alphabetical order.
I would like to keep the order of the endpoints set in the yaml or json file.

I did test with the pestore.yaml file by moving the store endpoints before the user endpoints but nothing changes in the generated html.

Describe the solution you'd like

To leverage the mustache templates, I would like to have a parameter that would let me organize the {{#apis}} and the {{#operations}} list in the mustache template.

  <h1>Methods</h1>
  {{#apiInfo}}{{#apis}}{{#operations}}
    <h2>{{baseName}}</h2>
    {{#operation}}
      <h3>{{nickname}} - {{summary}}</h3>

Describe alternatives you've considered

An alternative would be to have a config option that would be used by the java code generating these lists.

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 with the mustache template sections containing {{#apis}} and {{#operations}}, then reproduce the ordering behavior using pestore.yaml with store endpoints before user endpoints. Trace where the Java generator builds these lists and determine how a configuration option could preserve YAML or JSON order; done means generated HTML follows the input order.

Written by the indexing model from the issue text.

Assessment

Tech stack
java, openapi
Domain
api, documentation
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 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.