structuring-your-api-reference.md

description
Learn how to structure your API reference across multiple pages with icons and descriptions.

Structuring your API reference

GitBook does more than just render your OpenAPI spec. It lets you customize your API reference for better clarity, navigation, and branding.

Split operations across multiple pages

To keep your documentation organized, GitBook can split your API operations into separate pages. Each page is generated from a tag in your OpenAPI spec. To group operations into a page, assign the same tag to each operation:

paths:
  /pet:
    put:
      tags:
        - pet
      summary: Update an existing pet.
      description: Update an existing pet by Id.
      operationId: updatePet

Reorder pages in your table of contents

The order of pages in GitBook matches the order of tags in your OpenAPI tags array:

tags:
  - name: pet
  - name: store
  - name: user

Nest pages into groups

To build multi-level navigation, use x-parent (or parent) in tags to define hierarchy:

tags:
  - name: everything
  - name: pet
    x-parent: everything
  - name: store
    x-parent: everything

The above example will create a table of contents that looks like:

Everything
├── Pet
└── Store

If a page has no description, GitBook will automatically show a card-based layout for its sub-pages.

Customize page titles, icons, and descriptions

You can enhance pages with titles, icons, and descriptions using custom extensions in the tags section. All Font Awesome icons are supported via x-page-icon.

{% code title="openapi.yaml" %}

tags:
  - name: pet
    # Page title displayed in table of contents and page
    -x-page-title: Pet
    # Icon shown in table of contents and next to page title
    -x-page-icon: dog
    # Description shown just above the title
    -x-page-description: Pets are amazing!
    # Content of the page
    description: Everything about your Pets

{% endcode %}

Build rich descriptions with GitBook Blocks

Tag description fields support GitBook markdown, including advanced blocks like tabs:

{% code title="openapi.yaml" %}

---
tags:
  - name: pet
    description: |
      Here is the detail of pets.

      {% raw %}
{% tabs %}
      {% tab title="Dog" %}
      Here are the dogs
      {% endtab %}

      {% tab title="Cat" %}
      Here are the cats
      {% endtab %}

      {% tab title="Rabbit" %}
      Here are the rabbits
      {% endtab %}
      {% endtabs %}
{% endraw %}

{% endcode %}

Highlight schemas

You can highlight a schema in a GitBook description by using GitBook markdown. Here is an example that highlights the “Pet” schema from the “petstore” specification:

{% code title="openapi.yaml" %}

---
tags:
  - name: pet
      description: |
          {% raw %}
{% openapi-schemas spec="petstore" schemas="Pet" grouped="false" %}
              The Pet object
          {% endopenapi-schemas %}
{% endraw %}

{% endcode %}