Pular para o conteúdo principal

Arquivo de especificação de API

Um arquivo de especificação de API no formato JSON é um documento estruturado que descreve os detalhes de uma API, incluindo seus endpoints, métodos, parâmetros, tipos de resposta e autenticação. Esses arquivos são comumente usados com OpenAPI (Swagger) para padronizar e facilitar a comunicação entre sistemas e desenvolvedores.

Exemplo em JSON (OpenAPI 3.0):
{
  "openapi": "3.0.0",
  "info": {
    "title": "Exemplo de API",
    "version": "1.0.0"
  },
  "paths": {
    "/usuarios": {
      "get": {
        "summary": "Lista todos os usuários",
        "responses": {
          "200": {
            "description": "Lista de usuários retornada com sucesso"
          }
        }
      }
    }
  }
}
informação

É importante que o arquivo siga as especificações completas. Acesse a documentação do Swagger para saber mais.

Agora que você já sabe o que é um arquivo de especificação, vamos entender como disponibilizá-lo para conversão em MDX.

Salvar o arquivo na pasta specs​

  1. Primeiro tenha em mãos a URL do arquivo .json. Aqui usaremos o arquivo da API Petstore.
  2. Abra o um novo terminal powershell no VS Code

powershell

  1. Execute o comando
.\process_swagger.ps1 -ApiUrls @("https://petstore.swagger.io/v2/swagger.json")
dica

Se você possuir mais de uma API, você pode executar o comando separando as URLs por vírgulas.

Por exemplo:

.\process_swagger.ps1 -ApiUrls @("https://petstore.swagger.io/v2/swagger.json","https://petowner.swagger.io/v2/swagger.json")
  1. O arquivo será salvo na pasta specs

pasta specs

O próximo passo é Configurar a API.