Structuring your API reference
Learn how to structure your API reference across multiple pages with icons and descriptions.
Last updated
Was this helpful?
Learn how to structure your API reference across multiple pages with icons and descriptions.
Last updated
Was this helpful?
GitBook does more than just render your OpenAPI spec. It lets you customize your API reference for better clarity, navigation, and branding.
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:
The order of pages in GitBook matches the order of tags in your OpenAPI tags array:
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.
You can enhance pages with titles, icons, and descriptions using custom extensions in the tags section. All are supported via x-page-icon.
Tag description fields support GitBook markdown, including like tabs:
We’re currently improving how you build API documentation in GitBook. This page covers features that are being gradually rolled out. If you don’t see them yet, hang tight—they’re on the way!