Skip to main content

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:

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 path or group by tag?

Group by tag​

caution

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 :

Group Petstore operations by tag

info

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:

Group petstore operations by path

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.

caution

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.