search

gbif / tech-docs

This is an integrated technical documentation site for GBIF.org
https://techdocs.gbif.org
0 stars 2 forks source link

Customize ordering of methods in API documentation #10

Closed MattBlissett closed 1 year ago

MattBlissett commented 1 year ago

Customizing the ordering of "tags" (whole sections of the API, e.g. "Dataset" or "Dataset search") is possible by adding a Java bean. This alters the ordering of the content in the OpenAPI schema output.

However, methods are children of paths, so while it would be possible to rearrange paths in the schema output, it's not possible to rearrange each method. We can have:

GET /dataset/{key}
PUT /dataset/{key}
DELETE /dataset/{key}
GET /dataset/search
...

but we cannot have

GET /dataset/{key}
GET /dataset/search
PUT /dataset/{key}
DELETE /dataset/{key}
...

Ordering like that would need to be done in the Javascript UI. I think the methods could still be tagged with an extension to define the ordering.

MattBlissett commented 1 year ago

Done where needed, see https://github.com/gbif/checklistbank/commit/d65a071f34a6cfa5f74d227e48c8b0a305555252 for the method.

(Note the fallback to alphabetical order, which is used there.)