Theneo Custom Metadata

Theneo allows you to import additional configuration options directly from your OpenAPI specification using the x-theneo-metadata attribute. This custom extension provides more flexibility, allowing you to define a complex structure and additional settings for how your API documentation is organized and displayed, offering much more configuration than what’s possible with a traditional OpenAPI spec.

What does x-theneo-metadata do?

The x-theneo-metadata attribute gives you the ability to add sections, sub-sections, and other properties that control how your API documentation is structured. This lets you create a more detailed and customized hierarchy, offering more complex configuration options beyond the standard OpenAPI capabilities.

Key Features of x-theneo-metadata:

• menu: This array lets you organize your documentation into sections, which can include:

• name: The title of the section that will appear in the menu.

• description: A brief explanation of the section’s content.

• icon: (Optional) A visual icon that represents the section.

• openDefault: (Optional) Determines if the section should be expanded by default when the documentation is first loaded.

• isHeader: (Optional) Specifies whether the section is just a header with no further details or endpoints under it.

• isPrivate: (Optional) Allows you to mark sections as private, restricting them to specific users.

• viewers: (Optional) An array of email addresses for users who are permitted to view private sections.

• operationId: (Optional) Links a section or sub-section to a specific API operation (endpoint) using the operationId from your OpenAPI spec.

• subSections: Lets you create nested sections within a larger section, allowing 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
  subSections:
    - 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 is this useful for you?

By using x-theneo-metadata in your OpenAPI spec, you can define a much more complex and customizable structure for your API documentation. It allows you to create detailed sections, control visibility, and link directly to specific API operations. This flexibility goes beyond what a traditional OpenAPI spec can offer, giving you more control over how your API documentation is organized and presented.