O Mintlify converte especificações OpenAPI 3.0 e 3.1 (em formato JSON ou YAML) em documentações de API interativas e modernas. Em vez de construir e atualizar tabelas manuais de parâmetros, cabeçalhos de requisição e esquemas de resposta, as equipes de engenharia e redação técnica podem importar diretamente sua especificação. O Mintlify processa os endpoints, gera blocos de código prontos em várias linguagens de programação e disponibiliza um console interativo (Playground) que permite executar requisições em tempo real no navegador.
A plataforma adota o modelo de documentação como código (Docs-as-code). O arquivo de especificação OpenAPI reside no mesmo repositório Git que o conteúdo em Markdown, sob a coordenação do arquivo de configuração central (docs.json, ou mint.json em projetos legados). É possível escolher entre dois fluxos de trabalho: a geração totalmente automática sem manutenção manual de páginas, ou a vinculação direta de operações OpenAPI a arquivos MDX customizados para enriquecer a documentação com tutoriais, regras de negócio e diagramas arquiteturais.
Pré-requisitos e padrões suportados
Antes de iniciar a integração com o Mintlify, confirme se o seu arquivo atende aos seguintes requisitos:
- Versões suportadas: O Mintlify suporta nativamente a OpenAPI Specification (OAS) nas versões 3.0 e 3.1. Caso sua API ainda utilize a especificação Swagger 2.0, realize a conversão para OpenAPI 3.0 antes da importação.
- Formatos de arquivo: Há suporte integral para arquivos JSON (
.json) e YAML (.yamlou.yml). - Limitações de referências ($ref): O Mintlify resolve com precisão referências internas em um único documento (como
$ref: '#/components/schemas/User'). No entanto, referências externas divididas em arquivos separados não são suportadas. Se a sua especificação estiver fragmentada em múltiplos arquivos externos, consolide-os em um único arquivo (utilizando utilitários como Redocly CLI ou@apidevtools/swagger-cli) antes de importá-la.
Passo 1: Localização do arquivo de especificação OpenAPI
A inclusão da especificação pode ser feita por meio de armazenamento local no repositório ou por URL remota:
-
Repositório local (Recomendado): Adicione o arquivo diretamente ao repositório da sua documentação. A estrutura recomendada é colocá-lo na raiz do projeto (como
openapi.jsonouopenapi.yaml) ou em uma pasta dedicada (comoapi-reference/openapi.jsonouspecs/v1.yaml). -
Hospedagem via URL remota: Se o seu pipeline de CI/CD gera e publica automaticamente o arquivo OpenAPI atualizado em um serviço de armazenamento em nuvem ou CDN, basta fornecer a URL HTTPS direta (por exemplo,
https://api.example.com/specs/openapi.json). Para ambientes de produção, URLs remotas exigem obrigatoriamente conexão HTTPS.
Passo 2: Configuração de navegação no docs.json
Para exibir a seção de referência de API na barra lateral do site, vincule a especificação no bloco navigation do seu arquivo docs.json.
Abordagem A: Geração automática da referência
Se você deseja que o Mintlify descubra todos os endpoints, agrupe-os automaticamente com base nas tags (tags) do OpenAPI e crie as páginas de navegação sem a necessidade de criar arquivos manuais, declare o arquivo diretamente em uma aba ou grupo:
{
"$schema": "https://mintlify.com/docs.json",
"name": "Acme API Docs",
"navigation": {
"tabs": [
{
"tab": "Guias",
"groups": [
{
"group": "Primeiros Passos",
"pages": ["introduction", "quickstart"]
}
]
},
{
"tab": "API Reference",
"openapi": "openapi.json"
}
]
}
}
Nesse modo, o Mintlify lê todos os caminhos definidos sob paths, extrai métodos HTTP, títulos, parâmetros e esquemas de resposta, gerando a estrutura completa de documentação instantaneamente.
Gerenciamento de múltiplas especificações
Caso o seu sistema possua múltiplos microsserviços ou versões distintas de API, passe uma lista com os caminhos dos arquivos:
{
"navigation": {
"tabs": [
{
"tab": "API Reference",
"openapi": [
"specs/v1/auth.json",
"specs/v1/billing.json",
"specs/v2/core.json"
]
}
]
}
}
Passo 3: Controle granular com páginas MDX
Embora a automação completa seja prática, redactores técnicos frequentemente precisam incluir orientações contextuais, avisos de rate limit, requisitos prévios de permissão ou diagramas de fluxo. O Mintlify permite conectar páginas MDX a endpoints específicos usando o Frontmatter.
1. Vinculando um arquivo MDX a um endpoint específico
Crie um arquivo MDX (por exemplo, api-reference/users/create.mdx) e declare o método e a rota no campo openapi do cabeçalho Frontmatter:
---
title: "Criar Usuário"
sidebarTitle: "Criar Usuário"
description: "Registra uma nova conta de usuário dentro da organização"
openapi: "POST /v1/users"
---
## Requisitos Prévios
Antes de chamar este endpoint, certifique-se de que a aplicação cliente obteve o escopo de autorização `users:write`.
<Warning>
O endereço de e-mail deve ser exclusivo em toda a organização. Tentar cadastrar um e-mail já existente resultará no erro `409 Conflict`.
</Warning>
## Notificações via Webhook
Após a criação do usuário, a plataforma Acme dispara automaticamente o evento `user.created` para os endpoints de webhook configurados.
O Mintlify localiza a rota POST /v1/users na especificação OpenAPI e injeta automaticamente o console de testes e a listagem de parâmetros ao redor do seu conteúdo textual.
Se o projeto utilizar vários arquivos de especificação, especifique o caminho do arquivo para evitar conflitos de rota:
---
title: "Criar Usuário"
openapi: "specs/v1/auth.json POST /v1/users"
---
2. Criação em lote de páginas MDX com o utilitário oficial
Para gerar arquivos base para uma quantidade volumosa de rotas existentes, execute a ferramenta oficial de scraping:
npx @mintlify/scraping@latest openapi-file ./openapi.json -o api-reference
Esse comando analisa sua especificação e cria automaticamente todos os arquivos MDX correspondentes na pasta api-reference, já devidamente preenchidos com os metadados do Frontmatter.
Passo 4: Configurando o console interativo (Playground)
O console interativo do Mintlify possibilita testar requisições diretamente pela documentação. Para garantir uma experiência sem erros, ajuste os seguintes pontos:
1. Definindo o endereço base (Base URL)
O Mintlify extrai as URLs de destino diretamente da matriz servers na sua especificação:
servers:
- url: https://api.example.com/v1
description: Servidor de Produção
- url: https://staging.api.example.com/v1
description: Ambiente Sandbox
Ao cadastrar múltiplos servidores, o playground exibirá uma lista suspensa para alternância rápida de ambiente.
2. Esquemas de autenticação e valores de demonstração
Declare seus métodos de autenticação em components.securitySchemes. O console gerará os campos de entrada apropriados (Bearer Token, API Key, Basic Auth, etc.):
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: Insira seu token de acesso à API
security:
- bearerAuth: []
Para facilitar testes rápidos em ambientes sandbox, você pode fornecer chaves de teste seguras por meio da extensão x-default:
{
"components": {
"securitySchemes": {
"apiKey": {
"type": "apiKey",
"in": "header",
"name": "X-API-Key",
"x-default": "demo_pk_live_testing123"
}
}
}
}
3. Cuidados com CORS (Cross-Origin Resource Sharing)
Como as chamadas do console interativo partem diretamente do navegador do usuário, o servidor da API precisa aceitar requisições de origem cruzada:
Access-Control-Allow-Origin: *(ou o domínio específico da sua documentação)Access-Control-Allow-Methods: GET, POST, PUT, DELETE, PATCH, OPTIONSAccess-Control-Allow-Headers: Authorization, Content-Type, X-API-Key
Se a sua API rejeitar requisições de pré-verificação (OPTIONS), o playground apresentará erro de rede, mesmo que comandos executados via terminal (como curl) funcionem normalmente.
Passo 5: Customizações não destrutivas com OpenAPI Overlays
Em muitos cenários, a especificação exportada pelo código de backend contém rotas internas ou descrições técnicas inadequadas para o público final. Para evitar modificações manuais na especificação original, o Mintlify implementa a OpenAPI Overlay Specification (v1.1.0).
Um arquivo de sobreposição aplica alterações cirúrgicas usando sintaxe JSONPath (update, remove, copy):
overlay: 1.1.0
info:
title: Ajustes na Documentação Pública
version: 1.0.0
extends: ./openapi.json
actions:
- target: $.info.description
update: "Bem-vindo à documentação oficial para desenvolvedores da Acme. Explore nossos endpoints e teste requisições em tempo real."
- target: $.paths['/internal/system-health']
remove: true
- target: $.paths['/v1/billing'].post.summary
update: "Criar assinatura de cobrança recorrente"
Em seguida, aponte a sobreposição no arquivo docs.json:
{
"navigation": {
"tabs": [
{
"tab": "API Reference",
"openapi": {
"source": "openapi.json",
"overlays": ["overlays/public-filter.yaml"]
}
}
]
}
}
Durante a compilação, o Mintlify aplica as alterações sem alterar a fonte original da engenharia, removendo rotas privadas e aprimorando textos voltados aos clientes.
Passo 6: Validação local e integração CI/CD
Antes de publicar sua documentação, teste e valide as configurações em seu ambiente local com a CLI do Mintlify:
-
Instalar a CLI e iniciar o servidor local:
npm i -g mintlify mint dev -
Testar esquemas servidos localmente: Caso a especificação venha de um serviço local (como
http://localhost:8000/openapi.json), utilize a permissão apropriada:mint dev --local-schema -
Executar verificação estrita: Identifique esquemas corrompidos, parâmetros omissos ou erros de sintaxe:
mint validate -
Automação no pipeline de CI: Inclua a execução de
mint validateem suas automações do GitHub Actions ou GitLab CI. Quando os desenvolvedores submeterem mudanças na especificação da API, o pipeline validará a integridade antes do deploy, protegendo a estabilidade da documentação em produção.