​
Visão geral

O playground de API é um ambiente interativo que permite aos usuários testar e explorar seus endpoints de API. Desenvolvedores podem criar requisições de API, enviá-las e visualizar as respostas sem sair da sua documentação.
Playground de API para o endpoint que aciona uma atualização.
O playground é gerado automaticamente a partir da sua especificação OpenAPI ou do esquema AsyncAPI, de modo que quaisquer atualizações na sua API são refletidas automaticamente no playground. Você também pode criar manualmente páginas de referência de API após definir uma URL base e um método de autenticação no seu docs.json. Recomendamos gerar seu playground de API a partir de uma especificação OpenAPI. Consulte Configuração do OpenAPI para mais informações sobre como criar seu documento OpenAPI.

​
Introdução

1

Adicione seu arquivo de especificação OpenAPI.

Verifique se seu arquivo de especificação OpenAPI é válido usando o Swagger Editor ou o Mint CLI.
/your-project
  |- docs.json
  |- openapi.json
2

Configure `docs.json`.

Atualize seu docs.json para referenciar sua especificação OpenAPI. Adicione a propriedade openapi a qualquer elemento de navegação para preencher automaticamente sua documentação com páginas para cada endpoint definido no seu documento OpenAPI.Este exemplo gera uma página para cada endpoint definido em openapi.json e as organiza no grupo “API reference” na navegação.
"navigation": {
  "groups": [
    {
      "group": "API reference",
      "openapi": "openapi.json"
    }
  ]
}
Para gerar páginas apenas para endpoints específicos, liste-os na propriedade pages do elemento de navegação.Este exemplo gera páginas apenas para os endpoints GET /users e POST /users. Para gerar páginas de outros endpoints, adicione-os ao array pages.
"navigation": {
  "groups": [
      {
        "group": "API reference",
        "openapi": "openapi.json",
        "pages": [
          "GET /users",
          "POST /users"
        ]
      }
  ]
}

​
Personalizando seu playground

Você pode personalizar seu Playground de API definindo as seguintes propriedades no docs.json.
​
playground
object
Configurações do Playground de API.
​
examples
object
Configurações para os exemplos de API gerados automaticamente.

​
Exemplo de configuração

{
 "api": {
   "playground": {
     "display": "interactive"
   },
   "examples": {
     "languages": ["curl", "python", "javascript"],
     "defaults": "required"
   }
 }
}
Este exemplo configura o Playground de API para ser interativo, com snippets de código de exemplo para cURL, Python e JavaScript. Somente os parâmetros obrigatórios são exibidos nos snippets.

​
Páginas de endpoints personalizadas

Quando você precisar de mais controle sobre sua documentação de API, use a extensão x-mint na especificação OpenAPI ou crie páginas individuais em MDX para seus endpoints. Ambas as opções permitem que você:
  • Personalize os metadados da página
  • Adicione conteúdo adicional, como exemplos
  • Controle o comportamento do playground por página
A extensão x-mint é recomendada para que toda a documentação de API seja gerada automaticamente a partir da especificação OpenAPI e mantida em um único arquivo. Páginas individuais em MDX são recomendadas para APIs pequenas ou quando você quiser experimentar alterações por página. Para mais informações, consulte extensão x-mint e Configuração de MDX.

​
Leituras adicionais

  • Configuração do AsyncAPI para mais informações sobre como criar o seu esquema AsyncAPI e gerar páginas de referência de WebSocket.