Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

RFE: Sort the API endpoints alphabetically in the documentation. #7404

Closed
Luap99 opened this issue Aug 21, 2020 · 25 comments · Fixed by #12708
Closed

RFE: Sort the API endpoints alphabetically in the documentation. #7404

Luap99 opened this issue Aug 21, 2020 · 25 comments · Fixed by #12708
Assignees
@jwhonce
Labels
documentation Issue or fix is in project documentation kind/feature Categorizes issue or PR as related to a new feature. locked - please file new issue/PR Assist humans wanting to comment on an old issue or PR with locked comments.

Comments

@Luap99
Copy link
Member

Luap99 commented Aug 21, 2020

/kind feature

Description

The endpoints inside the RestAPI Documentation at https://docs.podman.io/en/latest/_static/api.html are grouped in categories which is good. But within each category the endpoints seem to be in a random order (see below). It would be nice if they were sorted alphabetically.

image
@openshift-ci-robot openshift-ci-robot added the kind/feature Categorizes issue or PR as related to a new feature. label Aug 21, 2020
@zhangguanzhang
Copy link
Collaborator

@rhatdan PTAL

@rhatdan
Copy link
Member

rhatdan commented Aug 24, 2020

SGTM. Could one of you open a PR to fix this.

@Luap99
Copy link
Member Author

Luap99 commented Aug 27, 2020

I have looked at the swagger documentation but didn't found a way to achieve the desired result. Maybe someone else finds/knows a way to do this.

@Luap99 Luap99 added documentation Issue or fix is in project documentation and removed kind/feature Categorizes issue or PR as related to a new feature. labels Aug 27, 2020
@rhatdan
Copy link
Member

rhatdan commented Aug 31, 2020

@baude @jwhonce Any ideas?

@vrothberg
Copy link
Member

https://stackoverflow.com/questions/24951268/sort-api-methods-in-swagger-ui looks promising.

@vrothberg
Copy link
Member

But I don't know how our docs are wired. @baude, in case you tackle it, I'd like to watch over your shoulders so I know what to tweak where.

vrothberg added a commit to vrothberg/libpod that referenced this issue Sep 15, 2020
@vrothberg
run/create: record raw image
a7c30a4 
Record the user-specified "raw" image name in the SpecGenerator, so we
can pass it along to the config when creating a container.  We need a
separate field as the image name in the generator may be set to the
ID of the previously pulled image - ultimately the cause of containers#7404.

Reverting the image name from the ID to the user input would not work
since "alpine" for pulling iterates over the search registries in the
registries.conf but looking up "alpine" normalizes to
"localhost/alpine".

Recording the raw-image name directly in the generator was the best of
the options I considered as no hidden magic from search registries or
normalizations (that may or may not change in the future) can interfere.
The auto-update backend enforces that the raw-image name is a
fully-qualified reference, so we need to worry about that in the front
end.

Fixes: containers#7407
Signed-off-by: Valentin Rothberg <rothberg@redhat.com>
@vrothberg vrothberg mentioned this issue Sep 15, 2020
Merged
vrothberg added a commit to vrothberg/libpod that referenced this issue Sep 15, 2020
@vrothberg
run/create: record raw image
ce6efad 
Record the user-specified "raw" image name in the SpecGenerator, so we
can pass it along to the config when creating a container.  We need a
separate field as the image name in the generator may be set to the
ID of the previously pulled image - ultimately the cause of containers#7404.

Reverting the image name from the ID to the user input would not work
since "alpine" for pulling iterates over the search registries in the
registries.conf but looking up "alpine" normalizes to
"localhost/alpine".

Recording the raw-image name directly in the generator was the best of
the options I considered as no hidden magic from search registries or
normalizations (that may or may not change in the future) can interfere.
The auto-update backend enforces that the raw-image name is a
fully-qualified reference, so we need to worry about that in the front
end.

Fixes: containers#7407
Signed-off-by: Valentin Rothberg <rothberg@redhat.com>
@jwhonce
Copy link
Member

jwhonce commented Sep 30, 2020 •
edited
Loading

@TomSweeneyRedHat @baude

From a quick read:

  • it appears we need to set properties on the redoc script. Manipulation of the yaml does not change the presentation order
  • we currently retrieve the redoc script on-demand from html

To fix:

  • We need to either set properties when running redoc script

  • Or, build json application combining redoc with properties and our swagger. Application provides most control on future changes and locks us into a version of redoc. This has greatest impact on CI/CD.

  • Either way, we need to

    • update operationId's in the swagger:operation comments to maintain desired sort order, examples that would work:
      • createNetworkCompat
      • createNetworkLibpod
      • <verb><object><differentiator>

I'm not a json application expert, this is all from the documentation.

How do we currently publish to podman.io?

@TomSweeneyRedHat
Copy link
Member

@jwhonce it doesn't get published to podman.io, it gets published to readthedocs via some make magic that @baude put together. We then do a redirect of docs.podman.io to readthedocs. Also readthedocs has some settngs you can select to make that look seamless.

eithe suggestion sounds at least slightly painful, I'll let @baude flip the coin.

@rhatdan rhatdan added the kind/feature Categorizes issue or PR as related to a new feature. label Oct 7, 2020
@github-actions
Copy link

github-actions bot commented Nov 7, 2020

A friendly reminder that this issue had no activity for 30 days.

@rhatdan
Copy link
Member

rhatdan commented Nov 7, 2020

@Luap99 @TomSweeneyRedHat @baude @jwhonce Anyone have a chance to look at this?

@TomSweeneyRedHat
Copy link
Member

Think we need a decision first from @baude and/or @umohnani8 about which direction to go as requested in @jwhonce 's comment a few back.

@baude
Copy link
Member

baude commented Dec 23, 2020

we need @jwhonce on this one ... i have no clue here.

@github-actions
Copy link

A friendly reminder that this issue had no activity for 30 days.

@rhatdan
Copy link
Member

rhatdan commented Jan 25, 2021

@Luap99 @jwhonce Any progress on figuring out what is going on here?

@rhatdan
Copy link
Member

rhatdan commented Feb 11, 2021

From my naive reading of this issue, it seems like an easy fix, is there a reason that this has not been solved other then people busy on other projects?

@Luap99 @baude @jwhonce ???

@github-actions
Copy link

A friendly reminder that this issue had no activity for 30 days.

@rhatdan
Copy link
Member

rhatdan commented Mar 15, 2021

@Luap99 @jwhonce Any progress on figuring out what is going on here?

@github-actions
Copy link

A friendly reminder that this issue had no activity for 30 days.

@vrothberg
Copy link
Member

friendly ping

@github-actions
Copy link

A friendly reminder that this issue had no activity for 30 days.

@github-actions
Copy link

A friendly reminder that this issue had no activity for 30 days.

@rhatdan
Copy link
Member

rhatdan commented Dec 26, 2021

This seems to be a never ending Issue, with noone coming up with good ideas.
@TomSweeneyRedHat Any chance you could look at this?
@flouthoc Any ideas?

@flouthoc
Copy link
Collaborator

flouthoc commented Dec 27, 2021 •
edited
Loading

Redoc maintains the order which is specified in spec swagger.yaml and go-swagger maintains the order which is defined by how our code is commented.

Solution 1.
We could reorder our code but this is non-scalable approach and hard to maintain.

Solution 2.
Patch go-swagger to sort swagger according to summary. Again this would be wrong since not all documenting solution use summary as title.

Solution 3.

Fix at redoc level since only redoc is responsible how operations are rendered. Redoc documents this new feature but it was never implemented sortOperationsAlphabetically: https://redoc.ly/docs/api-reference-docs/guides/migration-guide-2-0/#automated-sorting

I think solution 3 is the best.
Here is the PR for upstream: Redocly/redoc#1843
PR for downstream: #12708

@flouthoc flouthoc mentioned this issue Dec 27, 2021
Merged
@flouthoc
Copy link
Collaborator

Screenshot of fix:

swagger-fix

@rhatdan
Copy link
Member

rhatdan commented Dec 27, 2021

Great job @flouthoc

@github-actions github-actions bot added the locked - please file new issue/PR Assist humans wanting to comment on an old issue or PR with locked comments. label Sep 21, 2023
@github-actions github-actions bot locked as resolved and limited conversation to collaborators Sep 21, 2023
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees

@jwhonce jwhonce

Labels
documentation Issue or fix is in project documentation kind/feature Categorizes issue or PR as related to a new feature. locked - please file new issue/PR Assist humans wanting to comment on an old issue or PR with locked comments.
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

[CI:DOCS]: sort swagger operations alpabetically flouthoc/podman
9 participants
@jwhonce @rhatdan @baude @flouthoc @vrothberg @zhangguanzhang @TomSweeneyRedHat @openshift-ci-robot @Luap99