Theneo Custom Metadata

The x-theneo-metadata extension imports advanced structure and configuration straight from your OpenAPI spec.

What x-theneo-metadata does

It lets you add sections, sub-sections, and other properties that control your documentation’s structure — building a detailed, customized hierarchy that goes well beyond standard OpenAPI capabilities.

Key properties

• menu — an array that organizes your documentation into sections, each of which can include:
• name — the section title shown in the menu.
• description — a brief explanation of the section’s content.
• icon (optional) — a visual icon representing the section.
• openDefault (optional) — whether the section is expanded by default on load.
• isHeader (optional) — whether the section is just a header, with no endpoints of its own.
• isPrivate (optional) — mark a section private, restricting it to specific users.
• viewers (optional) — an array of email addresses permitted to view a private section.
• operationId (optional) — link a section to a specific API operation using the operationId from your spec.
• subSections — nested sections within a larger section for a more detailed breakdown.

Example

x-theneo-metadata:
  menu:
    - name: Pet endpoints
      description: "A section for managing pet-related API operations."
      icon: https://theneo-prod-public.s3.us-east-1.amazonaws.com/theneo/make/api-explorer.png
      subSections:
        - name: List Pets
          operationId: listPets
        - name: Get Pet information using ID
          operationId: showPetById
        - name: Add new pet
          operationId: createPets
    - name: Header Section
      openDefault: true
      isHeader: true
      subSections:
        - name: Private Section
          isPrivate: true
          viewers:
            - test@theneo.io
          description: "Details that only certain users can see."

Why it’s useful

With x-theneo-metadata, you define a far more complex, customizable structure for your documentation — creating detailed sections, controlling visibility, and linking directly to API operations. It gives you control over how your API reference is organized and presented that a traditional OpenAPI spec simply can’t.