Se você usa páginas individuais em MDX para seus endpoints de API, pode migrar para a geração automática de páginas a partir da sua especificação OpenAPI, preservando a capacidade de personalização de cada página. Isso pode ajudar a reduzir o número de arquivos que você precisa manter e melhorar a consistência da documentação da sua API. Você pode definir metadados e conteúdo para cada endpoint na sua especificação OpenAPI e organizar os endpoints onde quiser na navegação.

​
Migração via CLI

O comando mint migrate-mdx é a maneira recomendada de migrar de páginas de endpoint em MDX para páginas geradas automaticamente. Este comando:
  • Analisa a estrutura de navegação do seu docs.json.
  • Identifica páginas MDX que geram páginas de endpoints OpenAPI.
  • Extrai o conteúdo de arquivos MDX e o move para a extensão x-mint na sua especificação OpenAPI.
  • Atualiza o seu docs.json para referenciar diretamente os endpoints OpenAPI em vez dos arquivos MDX.
  • Exclui os arquivos MDX de endpoint originais.
Se você já tiver x-mint definido para um endpoint e também tiver uma página MDX com conteúdo para esse endpoint, o conteúdo em MDX substituirá as configurações existentes de x-mint.Se você tiver várias páginas MDX para o mesmo endpoint com conteúdos diferentes, o script usará o conteúdo da página que aparece por último no seu docs.json.A ferramenta de migração não oferece pré-visualização das alterações antes de aplicá-las.
1

Prepare sua especificação OpenAPI.

Certifique-se de que sua especificação OpenAPI seja válida e inclua todos os endpoints que você deseja documentar.Quaisquer páginas MDX que você quiser migrar devem ter o frontmatter openapi: referenciando um endpoint.
Valide seu arquivo OpenAPI usando o Swagger Editor ou o Mint CLI.
2

Instale o Mint CLI

Se necessário, instale ou atualize o Mint CLI.
3

Execute o comando de migração.

mint migrate-mdx

​
Etapas de migração manual

1

Prepare sua especificação OpenAPI.

Certifique-se de que sua especificação OpenAPI seja válida e inclua todos os endpoints que você deseja documentar.Para endpoints cujo conteúdo ou metadados você queira personalizar, adicione a extensão x-mint ao endpoint. Consulte extensão x-mint para mais detalhes.Para endpoints que você deseja excluir da documentação, adicione a extensão x-hidden ao endpoint.
Valide seu arquivo OpenAPI usando o Swagger Editor ou a Mint CLI.
2

Atualize sua estrutura de navegação.

Substitua as referências de páginas em MDX por endpoints OpenAPI no seu docs.json.
"navigation": {
  "groups": [
    {
      "group": "API Reference",
      "openapi": "/path/to/openapi.json",
      "pages": [
        "overview",
        "authentication",
        "introduction",
        "GET /health",
        "quickstart", 
        "POST /users",
        "GET /users/{id}",
        "advanced-features"
      ]
    }
  ]
}
3

Remova os arquivos MDX antigos.

Depois de verificar que a nova navegação está funcionando corretamente, remova os arquivos de endpoint em MDX que não são mais necessários.
Você pode personalizar como a documentação da sua API aparece na navegação.
Combine páginas de API geradas automaticamente com outras páginas: 
"navigation": {
  "groups": [
    {
      "group": "API Reference",
      "openapi": "openapi.json",
      "pages": [
        "api/overview",
        "GET /users",
        "POST /users", 
        "api/authentication"
      ]
    }
  ]
}

​
Várias versões da API

Organize diferentes versões da API usando abas ou grupos: 
"navigation": {
  "tabs": [
    {
      "tab": "API v1",
      "openapi": "specs/v1.json"
    },
    {
      "tab": "API v2", 
      "openapi": "specs/v2.json"
    }
  ]
}

​
Quando usar páginas MDX individuais

Considere manter páginas MDX individuais quando você precisar de:
  • Conteúdo altamente personalizado por endpoint, como componentes React ou exemplos extensos.
  • Layouts de página exclusivos.
  • Abordagens de documentação experimentais para endpoints específicos.
Para a maioria dos casos de uso, a navegação em OpenAPI oferece melhor capacidade de manutenção e consistência.