Describing enums

Learn how to add descriptions to enums.

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!

When an API operation includes an enum, you can add x-enumDescriptions to provide more context about each option. GitBook will display the enum values and their descriptions in a table next to the operation.

openapi.yaml

openapi: '3.0'
info: ...
components:
  schemas:
    project_status:
      type: string
      enum:
        - LIVE
        - PENDING
        - REJECTED
      x-enumDescriptions:
        LIVE: The project is live.
        PENDING: The project is pending approval.
        REJECTED: The project was rejected.