Structuring your API reference
Learn how to structure your API reference across multiple pages with icons and descriptions
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:updatePetReorder 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:userNest pages into groups
To build multi-level navigation, use x-parent (or parent) in tags to define hierarchy:
The above example will create a table of contents that looks like:
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.
Build rich descriptions with GitBook Blocks
Tag description fields support GitBook markdown, including advanced blocks like tabs:
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:
Document a webhook endpoint
GitBook supports OpenAPI 3.1, including webhook endpoints.
The webhooks field is part of OpenAPI 3.1, so your specification must declare an OpenAPI 3.1 version. You can define webhooks directly in your OpenAPI file, and GitBook renders them alongside your other API operations. For version support across OpenAPI docs, see OpenAPI compatibility .
Last updated
Was this helpful?