OpenAPI é uma especificação para descrever APIs. A Mintlify oferece suporte a documentos OpenAPI 3.0+ para gerar documentação de API interativa e mantê-la sempre atualizada.

​
Adicionar um arquivo de especificação OpenAPI

Para documentar seus endpoints com OpenAPI, você precisa de um documento OpenAPI válido em formato JSON ou YAML que siga a especificação OpenAPI 3.0+. Você pode criar páginas de API a partir de um ou de vários documentos OpenAPI.

​
Descrevendo sua API

Recomendamos os seguintes recursos para aprender e criar seus documentos OpenAPI.
O Guia do OpenAPI do Swagger é para o OpenAPI v3.0, mas quase todas as informações se aplicam à v3.1. Para mais informações sobre as diferenças entre v3.0 e v3.1, consulte Migrating from OpenAPI 3.0 to 3.1.0 no blog do OpenAPI.

​
Especificando a URL da sua API

Para habilitar recursos do Mintlify, como o Playground de API, adicione um campo servers ao seu documento OpenAPI com a URL base da sua API. 
{
  "servers": [
    {
      "url": "https://api.example.com/v1"
    }
  ]
}
Em um documento OpenAPI, diferentes endpoints da API são especificados por seus caminhos, como /users/{id} ou simplesmente /. A URL base define onde esses caminhos devem ser anexados. Para mais informações sobre como configurar o campo servers, consulte API Server and Base Path na documentação do OpenAPI. O Playground de API usa essas URLs de servidor para determinar para onde enviar as solicitações. Se você especificar vários servidores, um menu suspenso permitirá que os usuários alternem entre eles. Se você não especificar um servidor, o Playground de API usará o modo simples, pois não é possível enviar solicitações sem uma URL base. Se sua API tiver endpoints que existam em URLs diferentes, você pode substituir o campo de servidor para um determinado caminho ou operação.

​
Especificando a autenticação

Para habilitar a autenticação na sua documentação de API e no playground, configure os campos securitySchemes e security no seu documento OpenAPI. As descrições da API e o Playground de API adicionarão campos de autenticação com base nas configurações de segurança do seu documento OpenAPI.
1

Defina seu método de autenticação.

Adicione o campo securitySchemes para definir como os usuários se autenticam.Este exemplo mostra uma configuração de autenticação do tipo bearer.
{
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
2

Aplique a autenticação aos seus endpoints.

Adicione o campo security para exigir autenticação.
{
  "security": [
    {
      "bearerAuth": []
    }
  ]
}
Tipos comuns de autenticação incluem:
  • API keys: para chaves enviadas em header, query ou cookie.
  • Bearer: para tokens JWT ou OAuth.
  • Basic: para nome de usuário e senha.
Se diferentes endpoints da sua API exigirem métodos de autenticação distintos, você pode substituir o campo security para uma determinada operação. Para mais informações sobre como definir e aplicar autenticação, consulte Authentication na documentação do OpenAPI.

​
Extensão x-mint

A x-mint é uma extensão personalizada do OpenAPI que oferece controle adicional sobre como a documentação da sua API é gerada e exibida.

​
Metadados

Substitua os metadados padrão das páginas de API geradas adicionando x-mint: metadata a qualquer operação. Você pode usar qualquer campo de metadados válido no frontmatter de MDX, exceto openapi: 
{
  "paths": {
    "/users": {
      "get": {
        "summary": "Get users",
        "description": "Retrieve a list of users",
        "x-mint": {
          "metadata": {
            "title": "List all users",
            "description": "Fetch paginated user data with filtering options",
            "og:title": "Display a list of users"
          }
        },
        "parameters": [
          {
            // Configuração do parâmetro
          }
        ]
      }
    }
  }
}

​
Conteúdo

Adicione conteúdo antes da documentação de API gerada automaticamente usando x-mint: content: 
{
  "paths": {
    "/users": {
      "post": {
        "summary": "Create user",
        "x-mint": {
          "content": "## Pré-requisitos\n\nEste endpoint requer privilégios de administrador e possui limite de taxa.\n\n<Note>Os e-mails dos usuários devem ser exclusivos em todo o sistema.</Note>"
        },
        "parameters": [
          {
            // Configuração do parâmetro
          }
        ]
      }
    }
  }
}
A extensão content é compatível com todos os Componentes (Mintlify) de MDX e sua formatação.

​
Href

Altere a URL da página do endpoint na sua documentação usando x-mint: href: 
{
  "paths": {
    "/legacy-endpoint": {
      "get": {
        "summary": "Endpoint legado",
        "x-mint": {
          "href": "/deprecated-endpoints/legacy-endpoint"
        }
      }
    },
    "/documented-elsewhere": {
      "post": {
        "summary": "Endpoint especial",
        "x-mint": {
          "href": "/guides/special-endpoint-guide"
        }
      }
    }
  }
}
Quando x-mint: href está presente, o item de navegação passa a apontar diretamente para a URL especificada, em vez de gerar uma página de API.

​
MCP

Exponha seletivamente endpoints como ferramentas do Model Context Protocol (MCP) usando x-mint: mcp. Habilite apenas endpoints seguros para acesso público por ferramentas de IA.
​
mcp
object
A configuração do MCP para o endpoint.
{
  "paths": {
    "/users": {
      "post": {
        "summary": "Create user",
        "x-mint": {
          "mcp": {
            "enabled": true
          },
          // ...
        }
      }
    },
    "/users": {
      "delete": {
        "summary": "Delete user (admin only)",
        // No `x-mint: mcp` so this endpoint is not exposed as an MCP tool
        // ...
      }
    }
  }
}
Para mais informações, veja Model Context Protocol.

​
Preencher automaticamente páginas de API

Adicione um campo openapi a qualquer elemento de navegação no seu docs.json para gerar automaticamente páginas para endpoints OpenAPI. Você pode controlar onde essas páginas aparecem na sua estrutura de navegação, como seções de API dedicadas ou junto com outras páginas. O campo openapi aceita um caminho de arquivo no seu repositório de documentação ou uma URL para um documento OpenAPI hospedado. As páginas de endpoints geradas têm estes valores de metadados padrão:
  • title: O campo summary da operação, se presente. Se não houver summary, o título é gerado a partir do método HTTP e do endpoint.
  • description: O campo description da operação, se presente.
  • version: O valor version do âncora ou da aba pai, se presente.
  • deprecated: O campo deprecated da operação. Se true, um rótulo de obsoleto aparecerá ao lado do título do endpoint na navegação lateral e na página do endpoint.
Para excluir endpoints específicos das suas páginas de API geradas automaticamente, adicione a propriedade x-hidden à operação na sua especificação OpenAPI.
Há duas abordagens para adicionar páginas de endpoints à sua documentação:
  1. Seções de API dedicadas: Referencie especificações OpenAPI em elementos de navegação para seções de API dedicadas.
  2. Endpoints seletivos: Referencie endpoints específicos na sua navegação junto com outras páginas.

​
Seções de API dedicadas

Gere seções de API dedicadas adicionando um campo openapi a um elemento de navegação, sem incluir outras páginas. Todos os endpoints da especificação serão incluídos: 
"navigation": {
  "tabs": [
    {
        "tab": "API Reference",
        "openapi": "https://petstore3.swagger.io/api/v3/openapi.json"
    }
  ]
}
Você pode usar várias especificações OpenAPI em diferentes seções de navegação: 
"navigation": {
  "tabs": [
    {
      "tab": "API Reference",
      "groups": [
        {
          "group": "Users",
          "openapi": {
            "source": "/path/to/openapi-1.json",
            "directory": "api-reference"
          }
        },
        {
          "group": "Admin",
          "openapi": {
            "source": "/path/to/openapi-2.json",
            "directory": "api-reference"
          }
        }
      ]
    }
  ]
}
O campo directory é opcional e indica onde as páginas de API geradas são armazenadas no seu repositório de docs. Se não for especificado, o padrão é o diretório api-reference do seu repositório.

​
Endpoints seletivos

Quando você quiser ter mais controle sobre onde os endpoints aparecem na sua documentação, poderá referenciar endpoints específicos na navegação. Essa abordagem permite gerar páginas de endpoints de API junto com outros conteúdos.

​
Definir uma especificação OpenAPI padrão

Configure uma especificação OpenAPI padrão para um elemento de navegação. Em seguida, faça referência a endpoints específicos no campo pages: 
"navigation": {
  "tabs": [
    {
      "tab": "Getting started",
      "pages": [
        "quickstart",
        "installation"
      ]
    },
    {
      "tab": "API reference",
      "openapi": "/path/to/openapi.json",
      "pages": [
        "api-overview",
        "GET /users",
        "POST /users",
        "guides/authentication"
      ]
    }
  ]
}
Qualquer entrada em páginas que siga o formato METHOD /path gerará uma página de API para esse endpoint usando a especificação OpenAPI padrão.

​
Herança de especificação OpenAPI

As especificações OpenAPI são herdadas na hierarquia de navegação. Elementos de navegação filhos herdam a especificação OpenAPI do elemento pai, a menos que definam a própria: 
{
  "group": "API reference",
  "openapi": "/path/to/openapi-v1.json",
  "pages": [
    "overview",
    "authentication",
    "GET /users",
    "POST /users",
    {
      "group": "Orders",
      "openapi": "/path/to/openapi-v2.json",
      "pages": [
        "GET /orders",
        "POST /orders"
      ]
    }
  ]
}

​
Endpoints individuais

Faça referência a endpoints específicos sem definir uma especificação OpenAPI padrão, incluindo o caminho do arquivo: 
"navigation": {
  "pages": [
    "introduction",
    "user-guides",
    "/path/to/openapi-v1.json POST /users",
    "/path/to/openapi-v2.json GET /orders"
  ]
}
Essa abordagem é útil quando você precisa de endpoints individuais de diferentes especificações ou quer incluir apenas endpoints específicos.

​
Crie arquivos MDX para páginas de API

Para ter controle sobre páginas de endpoints individuais, crie páginas MDX para cada operação. Isso permite personalizar os metadados da página, adicionar conteúdo, omitir determinadas operações ou reordenar páginas na sua navegação, no nível da página. Veja um exemplo de página OpenAPI em MDX da MindsDB e como ela aparece na documentação publicada.

​
Especificar arquivos manualmente

Crie uma página MDX para cada endpoint e especifique qual operação do OpenAPI exibir usando o campo openapi no frontmatter. Quando você referencia uma operação do OpenAPI dessa forma, o nome, a descrição, os parâmetros, as respostas e o Playground de API são gerados automaticamente a partir do seu documento OpenAPI. Se você tiver vários arquivos OpenAPI, inclua o caminho do arquivo na referência para garantir que a Mintlify encontre o documento correto. Se você tiver apenas um arquivo OpenAPI, a Mintlify o detectará automaticamente.
Essa abordagem funciona independentemente de você ter definido uma especificação OpenAPI padrão na navegação. Você pode referenciar qualquer endpoint de qualquer especificação OpenAPI incluindo o caminho do arquivo no frontmatter.
Se quiser referenciar um arquivo OpenAPI externo, adicione a URL do arquivo ao seu docs.json. 
---
title: "Get users"
description: "Returns all plants from the system that the user has access to"
openapi: "/path/to/openapi-1.json GET /users"
deprecated: true
version: "1.0"
---
O método e o caminho devem corresponder exatamente à definição na sua especificação OpenAPI. Se o endpoint não existir no arquivo OpenAPI, a página ficará vazia.

​
Gerar arquivos MDX automaticamente

Use o scraper da Mintlify para gerar páginas MDX automaticamente para documentos OpenAPI extensos.
Seu documento OpenAPI deve ser válido; caso contrário, os arquivos não serão gerados automaticamente.
O scraper gera:
  • Uma página MDX para cada operação no campo paths do seu documento OpenAPI.
  • Se o seu documento OpenAPI for versão 3.1+, uma página MDX para cada operação no campo webhooks do seu documento OpenAPI.
  • Um array de entradas de navegação que você pode adicionar ao seu docs.json.
1

Gerar arquivos `MDX`.

npx @mintlify/scraping@latest openapi-file <path-to-openapi-file>
2

Especificar uma pasta de saída.

npx @mintlify/scraping@latest openapi-file <path-to-openapi-file> -o api-reference
Adicione a flag -o para definir a pasta onde os arquivos serão gerados. Se nenhuma pasta for especificada, os arquivos serão gerados no diretório de trabalho.

​
Crie arquivos MDX para esquemas OpenAPI

Você pode criar páginas individuais para qualquer esquema do OpenAPI definido no campo components.schema de um documento OpenAPI: 
---
openapi-schema: OrderItem
---

​
Webhooks

Webhooks são callbacks HTTP que sua API envia para notificar sistemas externos quando eventos ocorrem. Webhooks são compatíveis com documentos OpenAPI 3.1+.

​
Defina webhooks na sua especificação OpenAPI

Adicione o campo webhooks ao seu documento OpenAPI, junto com o campo paths. Para mais informações sobre como definir webhooks, consulte Webhooks na documentação do OpenAPI.

​
Referencie webhooks em arquivos MDX

Ao criar páginas MDX para webhooks, use webhook em vez de métodos HTTP como GET ou POST: 
---
title: "Example webhook"
description: "Triggered when an event occurs"
openapi: "path/to/openapi-file webhook example-webhook-name"
---
O nome do webhook deve corresponder exatamente à chave definida no campo webhooks da sua especificação OpenAPI.