Name and sort endpoints and webhooks
In the Bump.sh console, if you click on any of your documentations and select Customize UI in the left menu, you can scroll down to How to group operations?. There are three options available:
Automatically
The default behaviour of Bump.sh is automatic grouping based on the presence of a list of top-leveltags
. More on that in theGroup by tags
section.Group by tags
Group by path
But first let's provide a bit more context on endpoints and webhooks.
Endpoints and Webhooks are resources
REST APIs are composed of a set of possible requests, from server to server.
- In the API context, endpoints are most of the time URLs that provides the location of a specific resource on an API server.
With OpenAPI, endpoints are stored under the resource
paths
.
OR
- Webhooks are requests that can be generated from the API to the external server, after a specific event occurred. Webhooks are stored with OpenAPI 3.1 under resource
webhooks
Here's how we describe, sort and group these resources, based on an OpenAPI specification example. Below is an overview of the full specification you can find on OpenAPI Specification examples repo.
openapi: "3.0.0"
info:
title: Swagger Petstore
paths:
/pets:
get:
summary: List all pets
operationId: listPets
tags:
- all pets
# ...
post:
summary: Create a pet
operationId: createPets
tags:
- single pet
# ...
/pets/{petId}:
get:
summary: Info for a specific pet
operationId: showPetById
tags:
- single pet
# ...
There are three operations here, and three different ways to generate, group and order them, regarding option chosen for How to group operations?
Group by tag
Be careful about operations without tags when option Group operations by tag
is selected, as they would be ignored!
You may have noticed in the above API Contract that there are two different tags
: all pets
and single pet
.
If you choose option Group by tag
, Bump.sh will use these tags
to group, name and sort the operations.
Here is our Petstore live example, based on the OpenAPI specification, with option Group by tag
:
If first level field tags
are present at the root of your OpenAPI document object, Bump.sh will use Group by tags
as a default documentation generation behaviour.
Having this first level field tags
allows you to override how your endpoints
are ordered. Take the following API Contract sample:
tags:
- name: single pet
description: all operations related to managing a single pet
- name: all pets
description: all operations related to managing all pets
paths:
# ...
With these first level tags, endpoints Single Pet
would be displayed above All pets
in the left menu of your documentation.
Note that you can also provide a description
for your tags
. This description will be displayed just under the name
of the tag
at the top level of your tag
documentation page.
This option Group by tag
allows a better customization of your doc, by overriding resources name.
Group by path
In this case, we deduce endpoint name from related path
. First part of the path is extracted to generate the endpoint
name, and every operation related to this endpoint name will be grouped together.
Let's Bump it up to something visual with a Petstore live example:
Operations GET
and POST
from /pets
, and GET
from /pets/{petId}
are grouped under same endpoint Pets
(first part of the path), and their names are generated from field summary
.
Webhooks
And what about webhooks?
It's quite well explained how webhooks name are generated from summary
, description
in Webhooks documentation's page. But by choosing option Group by tag
, webhooks
are displayed, grouped and ordered with same rules as for endpoints
.
Be careful about webhooks without tags when option Group by tag
is selected, as they would be ignored!
Two possibilities for this OpenAPI 3.1 documentation with endpoints and webhooks, on our examples hub:
Finally, we hope these options will help you build the most readable documentations, feel free to contact us if you need support or have some suggestion.