-
Notifications
You must be signed in to change notification settings - Fork 98
[OpenAPI] Merge multiple paths in a single operation #4415
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.
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
base: main
Are you sure you want to change the base?
Conversation
Looking at the current output, for example:
IMO if it make it more usable in general to just accomplish this list via simple markdown, that's okay too. For example:
|
The generated markup uses the CSS classes used by Bump in the main path description to provide a consistent rendering. I've added a commit that removes the
Yes. As we already discussed, it cannot replace the current OpenAPI file. It has to be a new one, dedicated to the docs pipeline.
So I understand we're good on that front? Some background: when we generate one operation for each method+path, the first one (as found in schema.json) has a "plain" (no suffix) identifier, and the others have a counter suffix ( |
Good to know there will be a dedicated OpenAPI file for the docs. This should also make it trivial to convert GHF markdown admonitions to the bump.sh syntax. |
That's great and should make it easier to check we don't have any of those suffixed URLs used elsewhere. |
Fixes #4277
Adds an option in the OpenAPI export to group the many operations resulting from endpoints with multiple paths in a single operation. This works around the current issue where there are many duplicated operations in the nav bar and in the documentation.
A "main path" is chosen to become the path of the single OpenAPI operation that is produced. This is the endpoint's longest path, which will show all path parameters, be them required or optional. All paths are then listed at the top of the description (including the main one), see rendering below.
WIP: do not merge this PR now. This option must be configurable, as it is destructive from an OpenAPI schema perspective since it removes some operations.
Search endpoint rendered by Bump with this PR: