O que é o API Docs

O API Docs é um editor e visualizador de documentação de APIs REST em um único arquivo HTML. ^[1] Ele mostra os endpoints de uma API, permite testá-los no navegador e exporta a documentação para OpenAPI, Postman, testes em Python, InterSystems IRIS, Markdown e PDF. Os dados ficam guardados dentro do próprio arquivo: para compartilhar a documentação, basta enviar o HTML.

Abrir o API Docs →

Este tutorial tem duas metades. A primeira explica a teoria que está por trás de cada campo da tela: o que é uma API, como é uma requisição HTTP, o que significam os códigos de status, como funciona a autenticação e por que existe o padrão OpenAPI. A segunda é um roteiro prático: você vai documentar e testar uma API pública de verdade, o ViaCEP, e exportar o resultado. No fim, prompts de IA prontos para copiar aceleram cada etapa.

O que você precisa

• Um navegador atual. Chrome e Edge gravam direto no arquivo; nos outros, salvar baixa uma cópia.
• Conexão com a internet só para testar requisições e para importar por URL. Ver, editar, importar arquivo e exportar funcionam sem rede.
• Nenhum conhecimento prévio de programação. Quem já programa vai aproveitar mais as seções de exportação.

O que é uma API

API quer dizer Application Programming Interface, ou interface de programação de aplicações. É um contrato entre dois programas: um deles, o servidor, oferece funções; o outro, o cliente, pede essas funções seguindo regras combinadas. Um aplicativo de entregas que preenche o endereço a partir do CEP não tem a base de CEPs do país: ele pergunta a uma API e recebe a resposta pronta.

O contrato diz o que pode ser pedido, como pedir e o que volta. Ele não diz como o servidor faz o trabalho por dentro. É isso que permite trocar o banco de dados ou a linguagem do servidor sem quebrar os clientes, desde que o contrato continue o mesmo. Documentar uma API é escrever esse contrato de forma que pessoas e programas consigam lê-lo.

REST

A maior parte das APIs da web segue, em maior ou menor grau, o estilo REST (Representational State Transfer), descrito por Roy Fielding em sua tese de doutorado de 2000. ^[2] Fielding define REST como um conjunto de restrições de arquitetura. As que mais aparecem no dia a dia são:

• Cliente e servidor separados. Cada lado evolui sem depender do outro.
• Sem estado (stateless). Cada requisição traz tudo o que o servidor precisa para atendê-la, inclusive a credencial. O servidor não “lembra” da conversa anterior.
• Cache. A resposta diz se pode ser reaproveitada, o que poupa idas ao servidor.
• Interface uniforme. Tudo é um recurso identificado por um endereço (o endereço de um CEP, a lista de pedidos de um cliente), e as operações sobre ele usam os mesmos poucos verbos do HTTP.

Na prática, “API REST” costuma significar uma API que usa HTTP, organiza os endereços por recursos e troca dados em JSON. O API Docs documenta exatamente esse tipo de API.

Anatomia de uma requisição

Cliente e servidor conversam por HTTP. Cada conversa é um par: o cliente manda uma requisição e o servidor devolve uma resposta. O significado de cada parte é definido pela RFC 9110, a norma atual da semântica do HTTP. ^[3]

A URL: servidor, caminho e parâmetros

O endereço de um recurso é uma URL, cuja sintaxe é definida pela RFC 3986. ^[4] No API Docs, a URL é montada a partir de três campos que você preenche separadamente:

Servidor (URL base)

O começo comum a todos os endereços, como https://api.correios.com.br. Uma API pode ter vários: produção, homologação, local.

Caminho

O recurso dentro do servidor, como /cep/v2/enderecos/{cep}. As chaves marcam um pedaço variável.

Parâmetro de caminho (path)

O valor que entra no lugar das chaves. Identifica qual recurso: 01001001. É sempre obrigatório.

Parâmetro de consulta (query)

Pares nome=valor depois do ?, separados por &. Filtram, ordenam ou paginam: ?uf=SP&size=50. Costumam ser opcionais.

Cabeçalho (header)

Informação sobre a requisição, fora da URL: formato aceito (Accept), credencial (Authorization), idioma.

Cookie

Valor que o navegador guarda e reenvia ao mesmo servidor. Raro em APIs consumidas por outros sistemas.

Esses quatro lugares são exatamente as opções da coluna Local dos parâmetros no app: path, query, header e cookie.

Os métodos

O método diz o que fazer com o recurso. A RFC 9110 classifica os métodos por duas propriedades que afetam a segurança e as novas tentativas: seguro é o método que, por definição, só lê; idempotente é aquele em que repetir a mesma requisição tem o mesmo efeito que fazê-la uma vez. ^[3]

Por que isso importa: se a rede cair no meio de um PUT, o cliente pode repetir sem medo; repetir um POST pode criar dois pedidos. É por isso que os testes exportados pelo app não executam métodos que alteram dados, a não ser que você autorize.

O corpo e o JSON

Requisições POST, PUT e PATCH levam dados no corpo. O cabeçalho Content-Type diz o formato; em APIs REST, quase sempre é application/json. JSON é um formato de texto com objetos entre chaves, listas entre colchetes, textos entre aspas, números e os valores true, false e null, definido pela RFC 8259. ^[5]

{
  "numero": "9912345678",
  "dr": 10
}

Uma requisição GET não deve levar corpo: a RFC 9110 diz que conteúdo em um GET não tem significado definido. ^[3] Por isso o app não mostra o campo de corpo para GET e HEAD.

Respostas e códigos de status

Toda resposta começa com um código de três dígitos. O primeiro dígito diz a família, e é isso que o app usa para colorir os selos das respostas. ^[3]

A distinção entre 4xx e 5xx diz de quem é a culpa e, portanto, quem precisa agir. Uma boa documentação lista também as respostas de erro, com um exemplo do corpo, porque é nelas que o desenvolvedor do cliente mais precisa de ajuda.

Autenticação

A maioria das APIs precisa saber quem está pedindo. Como o REST é sem estado, a credencial vai em toda requisição, em geral no cabeçalho Authorization. O app oferece os quatro esquemas mais comuns em Editar → Autenticação:

No app, a autenticação vale para todos os endpoints. Ao testar, os campos de credencial aparecem no painel Testar requisição. Eles ficam só na memória e não são gravados no arquivo ao salvar.

Documentar com OpenAPI

Uma documentação escrita em texto livre serve para pessoas, mas não para programas. A Especificação OpenAPI resolve isso: ela define uma descrição padronizada e independente de linguagem para APIs HTTP, que pessoas e computadores conseguem ler sem acesso ao código-fonte. ^[8] O documento OpenAPI é um objeto JSON, que pode ser escrito em JSON ou em YAML. ^[8]

Um pouco de história

O formato nasceu como Swagger, na empresa Wordnik. A Wikipédia situa a criação em 2010; o histórico de revisões da própria especificação registra a versão 1.0 em 10/08/2011 e o Swagger 2.0 em 08/09/2014. ^{[10] [8]} Em 2015, a especificação foi doada à OpenAPI Initiative, sob a Linux Foundation, e passou a se chamar OpenAPI. A data da doação diverge entre as fontes: a Wikipédia cita o anúncio da iniciativa em novembro de 2015, e o histórico da especificação registra a doação em 31/12/2015. A versão 3.0.0 saiu em 26/07/2017, e a 3.0.3, que é a que o app exporta, em 20/02/2020. ^[8] Já existem versões mais novas: a 3.2.0 foi publicada em setembro de 2025. ^[9] O nome Swagger continua vivo nas ferramentas da SmartBear, como o Swagger UI, e por isso as pessoas ainda dizem “o Swagger da API”.

Por que um padrão ajuda

• Uma fonte, vários usos. Do mesmo arquivo saem a página de documentação, coleções para ferramentas de teste, clientes gerados em várias linguagens e esqueletos de servidor.
• Contrato antes do código. No estilo design-first, a equipe escreve e discute a especificação antes de programar, e cliente e servidor podem ser desenvolvidos em paralelo. No estilo code-first, a especificação é gerada a partir do código já pronto. O API Docs atende o primeiro estilo e também importa o resultado do segundo.
• Verificável. Um documento OpenAPI pode ser validado por programa, e testes podem conferir se a API real cumpre o que está escrito.

Onde cada campo do app vai parar

Cada campo do app corresponde a uma parte do documento OpenAPI exportado. Conhecer essa relação ajuda a ler qualquer arquivo OpenAPI que você encontrar.

Os schemas descrevem a forma de um objeto: quais campos tem e de que tipo. O OpenAPI 3.0 usa para isso um subconjunto estendido do JSON Schema. ^[8]

Primeiros passos com o exemplo

O arquivo vem com uma documentação de exemplo, “API Busca CEP — Correios”. Ela serve para ver como uma API completa aparece no app: autenticação por token, um endpoint de geração de token, consulta, pesquisa paginada e um schema. A própria descrição do exemplo avisa que caminhos e campos devem ser conferidos no portal oficial dos Correios antes de qualquer uso real. ^[1] Em cinco minutos:

1. Abra o API Docs. Ele começa no modo Visualizar, com a visão geral: título, versão, descrição, servidor e o tipo de autenticação.
2. Na barra lateral, clique em GET /cep/v2/enderecos/{cep}. O cartão do endpoint se abre com a descrição, a tabela de parâmetros e as respostas. O asterisco vermelho ao lado de cep marca um parâmetro obrigatório.
3. Repare nas cores: GET azul, POST verde; respostas 2xx em verde, 4xx em laranja e 5xx em vermelho.
4. No campo Filtrar endpoints…, digite token. Sobra só o endpoint de autenticação. Apague o filtro.
5. No fim da barra lateral, clique em Endereco, em Schemas. A definição do objeto aparece em JSON.

No fim de cada cartão aberto fica o painel Testar requisição. Não o use com o exemplo dos Correios: a API exige contrato e token. O teste de verdade fica para a próxima seção, com uma API aberta.

Seu primeiro documento: ViaCEP

O ViaCEP é um serviço gratuito de consulta de CEP que não exige cadastro. A consulta é um GET em viacep.com.br/ws/{cep}/json/, com o CEP em 8 dígitos. ^[12] O roteiro abaixo foi executado com cliques reais no app em 11/11/2026.

1. Comece um documento em branco

1. Se quiser guardar o exemplo, salve antes uma cópia do arquivo.
2. Clique em Novo e confirme. O app passa ao modo Editar, na página Informações gerais.

2. Preencha as informações gerais

1. Título: ViaCEP. Versão: 1.0. A versão é a da sua documentação; quando o contrato mudar, aumente-a.
2. Descrição: um parágrafo sobre a API. O campo aceita Markdown simples: **negrito**, `código`, links e listas com “- ”.
3. Em Servidores, troque a URL base para https://viacep.com.br, sem barra no final, e a descrição para Produção.

A autenticação fica em Nenhuma, que já é o padrão de um documento novo.

3. Crie o endpoint

1. Na barra lateral, clique em + Endpoint. Um GET /novo-recurso aparece.
2. Caminho: /ws/{cep}/json/. Resumo: Consultar um CEP. Tag: CEP. A tag agrupa endpoints na barra lateral.
3. Clique em Detectar {parâmetros} do caminho. O app lê as chaves do caminho e cria o parâmetro cep, local path, obrigatório.
4. Na linha do parâmetro, escreva a descrição CEP com 8 dígitos, sem hífen e o exemplo 01001000. O exemplo é o valor que o painel de teste usa de início.

4. Documente as respostas

1. Na resposta 200 que já existe, escreva a descrição: Endereço encontrado. CEP inexistente também volta 200, com o campo `erro`.
2. Em Exemplo de resposta, cole um JSON curto e clique em Formatar JSON:

   {"cep":"01001-000","logradouro":"Praça da Sé","complemento":"lado ímpar","bairro":"Sé","localidade":"São Paulo","uf":"SP","ddd":"11"}

   Se o JSON estiver errado, a caixa fica vermelha com o aviso “JSON inválido”.
3. Clique em + Resposta, escreva o código 400 e a descrição Formato inválido (não tem 8 dígitos).

5. Teste de verdade

1. Clique em Visualizar e, na barra lateral, em GET /ws/{cep}/json/.
2. No painel Testar requisição, o campo cep já traz 01001000, e a URL completa aparece ao lado do botão.
3. Clique em Executar. Em menos de um segundo, no teste deste tutorial, chegou 200 OK com o endereço da Praça da Sé.

Compare a resposta real com o exemplo que você escreveu: ela tem campos a mais. Isso é comum, e é por isso que os testes exportados conferem só se os campos documentados existem, e não se a resposta é idêntica. Se quiser uma documentação completa, copie a resposta real para o exemplo.

6. Provoque um erro

1. Troque o CEP para 0100100, com 7 dígitos, e execute. O app mostra Falha na requisição: “Failed to fetch”.
2. Troque para 99999999 e execute. Volta 200 OK com {"erro": "true"}.

O primeiro caso parece uma queda da API, mas não é. A seção Testar requisições e CORS explica o que aconteceu. No segundo, a documentação do ViaCEP mostra "erro": true, booleano, e a resposta real trouxe "true", texto. ^[12] Esse tipo de diferença é exatamente o que testar a documentação revela.

7. Salve e exporte

1. Clique em Salvar (Ctrl+S) e grave, por exemplo, como viacep.html. Esse arquivo já é a documentação pronta para enviar.
2. Em Exportar ▾ → OpenAPI 3, o app baixa viacep-openapi.json. No teste deste tutorial, esse arquivo passou na validação do pacote @apidevtools/swagger-parser, que confere o documento contra o esquema oficial do OpenAPI 3.0.
3. Em Exportar ▾ → Testes Python, o app baixa test_viacep.py. Executado com pytest, o teste passou contra o ViaCEP real.

A interface

Barra superior

Título e versão da API, o aviso ● não salvo, a chave Visualizar / Editar, e os botões Salvar, Exportar ▾, Importar ▾ e Novo.

Barra lateral

O campo Filtrar endpoints…, que procura no método, no caminho, no resumo e na tag; os endpoints agrupados por tag; e os schemas. No modo Editar, ganha Informações gerais, Autenticação, Tags, + Endpoint e + Schema.

Área central

No modo Visualizar, a documentação navegável com o painel de teste em cada endpoint. No modo Editar, o formulário do item escolhido na barra lateral.

Avisos

Mensagens curtas aparecem por alguns segundos no rodapé da tela: arquivo salvo, parâmetros detectados, erro de importação.

Em telas com menos de 860 px de largura, a barra lateral some e a navegação fica só pela rolagem da área central.

O modo Editar em detalhe

Parâmetros

Cada linha tem nome, local (path, query, header, cookie), tipo, a marca de obrigatório, descrição e exemplo. Um parâmetro de caminho é sempre obrigatório: a especificação OpenAPI exige isso, e o app aplica a regra ao exportar, mesmo que a marca esteja desligada. ^[8] Os tipos integer, number e boolean fazem o exemplo ser exportado como número ou booleano, e não como texto.

Corpo e respostas

O Content-Type sugere os tipos mais comuns. Os campos de exemplo com JSON validam enquanto você digita e têm o botão Formatar JSON. Um exemplo que não é JSON é aceito, mas tratado como texto.

Endpoints marcados como obsoletos aparecem riscados e com o selo “obsoleto”. É a forma padrão de avisar que algo vai sair, sem remover de repente.

Testar requisições e CORS

O painel Testar requisição monta a URL com o servidor escolhido, preenche os parâmetros com os exemplos, inclui a credencial digitada e envia a requisição pelo próprio navegador. O resultado mostra o código, o tempo, os cabeçalhos da resposta, o comando curl equivalente e o corpo formatado.

Por que o navegador bloqueia algumas chamadas

Por segurança, o navegador só deixa um script ler a resposta de outro site se esse site autorizar, com o cabeçalho Access-Control-Allow-Origin. Esse mecanismo se chama CORS (Cross-Origin Resource Sharing). ^[11] Sem a autorização, o navegador entrega ao script apenas um erro genérico, e o app mostra “Failed to fetch”.

Foi o que aconteceu com o CEP de 7 dígitos. Chamado fora do navegador, o ViaCEP respondeu 400 Bad Request com uma página HTML e sem o cabeçalho CORS; a consulta válida voltou com Access-Control-Allow-Origin: *. O erro existia, mas o navegador o escondeu.

Além disso, requisições com Authorization, com Content-Type: application/json ou com métodos como PUT e DELETE passam antes por uma consulta OPTIONS, a preflight, que o servidor também precisa aprovar. ^[11] Muitas APIs corporativas não liberam CORS para qualquer origem.

O que fazer quando o teste falha

1. Abra Comando curl, clique em Copiar curl e rode no terminal. O curl não é navegador e não aplica CORS: você vê o código e o corpo verdadeiros.
2. Se o curl funcionar, a API está no ar e o bloqueio é do navegador. Documente normalmente; o teste no app é que não é possível.
3. Se o curl também falhar, confira o servidor, o caminho, a credencial e a rede.

Salvar

O app não usa servidor nem banco de dados. A documentação fica em um bloco JSON dentro do próprio HTML, e salvar é gravar um novo HTML com esse bloco atualizado.

O que não é gravado: as credenciais digitadas no teste, os valores alterados no painel de teste e os resultados das chamadas. Se você tentar fechar a aba com alterações pendentes, o navegador pede confirmação.

Importar

Muitas APIs já têm uma especificação, gerada pelo próprio framework do servidor. Importar evita digitar tudo de novo.

Se o documento atual já tiver endpoints, o app pergunta o que fazer:

• Mesclar acrescenta endpoints, tags, servidores e schemas que ainda não existem. Um endpoint com o mesmo método e caminho de outro já existente é ignorado. No teste, mesclar o ViaCEP ao exemplo dos Correios resultou em 5 endpoints.
• Substituir tudo descarta a documentação atual.

Quando um exemplo não existe na especificação de origem, o app cria um a partir do schema, com valores genéricos como "string" e 0. Revise esses exemplos depois de importar.

Exportar

Os testes em Python

O arquivo gerado traz no topo as instruções de instalação e execução. Cada teste chama um endpoint com os valores de exemplo, confere o código de sucesso documentado e verifica se os campos do exemplo de resposta existem na resposta real com o mesmo tipo JSON.

pip install pytest requests
pytest -v test_viacep.py

• A URL base e as credenciais vêm de variáveis de ambiente: API_BASE_URL, API_TOKEN, API_USER e API_PASS, ou API_KEY. Assim, nenhuma senha fica no código.
• Métodos que alteram dados (POST, PUT, PATCH, DELETE) só rodam com API_ALLOW_WRITE=1. Sem isso, aparecem como pulados.
• Se a API tem autenticação e o endpoint documenta a resposta 401, o app cria também um teste sem credencial, que espera 401.
• API_MAX_MS define um tempo máximo de resposta, se você quiser vigiar a lentidão.

Prompts de IA

Uma IA acelera as partes demoradas da documentação: levantar endpoints espalhados pelo código, transformar chamadas soltas em uma especificação, escrever descrições e ampliar testes. Ela também erra com segurança: inventa campos, chuta códigos de status e descreve comportamentos que a API não tem. Trate a saída como rascunho e confira cada endpoint com o painel Testar requisição, que fala com a API de verdade. Para escrever prompts melhores, veja o tutorial de prompts.

Antes de colar: tire tokens, senhas, chaves de API, endereços internos e dados de clientes do que vai para a IA. Troque por valores fictícios e siga a política da sua organização. O app só se comunica com a API que você testa, mas o serviço de IA recebe tudo o que você colar nele.

Troque os trechos entre colchetes e cole na ferramenta de IA que você usa. Os prompts seguem a ordem do trabalho: os de 1 a 4 produzem a documentação, e os de 5 a 9 a revisam e a colocam em uso. Cada um funciona sozinho.

1. Entrevistar antes de documentar

Quando a API ainda está na cabeça de quem a fez. A IA pergunta, em vez de supor.

Você é um redator técnico experiente em APIs REST e na especificação OpenAPI.
Quero documentar esta API: [descreva em poucas frases o que ela faz e quem a usa].

Antes de escrever qualquer documentação, me entreviste:
- Faça uma pergunta por vez e espere minha resposta.
- Cubra: URL base de cada ambiente; forma de autenticação; cada recurso e as operações sobre ele (método e caminho); parâmetros de caminho, de consulta e de cabeçalho, com tipo, obrigatoriedade e um exemplo; corpo das requisições; respostas de sucesso e de erro, com o código e um exemplo de corpo; paginação; limites de uso; o que está obsoleto.
- Pergunte principalmente sobre os erros: o que acontece com dado inválido, sem credencial, sem permissão e com recurso inexistente.
- Não invente respostas. Se eu não souber, registre como pendência.

Ao final, entregue: uma tabela de endpoints (método, caminho, resumo, tag), a lista de parâmetros e respostas de cada um, exemplos de corpo em JSON e a lista de pendências.

2. Levantar endpoints a partir do código

Para APIs já programadas sem documentação. Pede a origem de cada item, o que facilita conferir.

A partir do código abaixo, levante o contrato da API REST que ele implementa.

Linguagem e framework: [por exemplo: Java com Spring, C# com ASP.NET, Node com Express, Python com FastAPI, ObjectScript com %CSP.REST]
Código:
[cole os controladores, rotas ou o UrlMap, e as classes de entrada e saída]

Entregue:
1. Tabela de endpoints: método, caminho (com {parâmetros}), resumo, tag sugerida e o arquivo e a linha de onde saiu.
2. Para cada endpoint: parâmetros (nome, local path, query, header ou cookie, tipo, obrigatório), corpo da requisição com um exemplo em JSON, e respostas com código e exemplo de corpo.
3. Os códigos de erro que o código realmente devolve, e em que situação.
4. Como a autenticação é verificada.
5. Lacunas: retornos que dependem de código que não está aqui, exceções não tratadas e comportamentos ambíguos, com uma pergunta para cada um.

Não deduza o que o código não mostra. Use exemplos fictícios.

3. Gerar o OpenAPI para importar no app

Transforma o que você reuniu em um arquivo que o app importa de uma vez, em vez de digitar endpoint por endpoint. O formato pedido é o que o importador do app aproveita.

Gere uma especificação OpenAPI 3.0.3 em JSON para a API descrita no fim. Ela será importada no API Docs, um editor que lê um subconjunto do OpenAPI.

Responda só com o JSON, sem comentários e sem cercas de código.

Use apenas estes elementos:
- "openapi": "3.0.3" e "info" com "title", "version" e "description". A descrição aceita Markdown simples: **negrito**, `código`, links e listas com "- ".
- "servers": lista com "url" (sem barra no final) e "description".
- "tags": lista com "name" e "description". Cada operação usa uma só tag.
- "paths": uma operação por método (get, post, put, patch, delete), com "tags", "summary" (curto, começando por verbo), "description" e, se for o caso, "deprecated": true.
- "parameters": "name", "in" (path, query, header ou cookie), "required", "description", "schema" com "type" (string, integer, number, boolean, array ou object) e "example". Todo {parâmetro} do caminho precisa de um parâmetro com "in": "path" e "required": true.
- "requestBody" só em post, put e patch: "description" e "content" com um único tipo de mídia, em geral "application/json", contendo "example".
- "responses": para cada código, "description" e, quando houver corpo, "content": {"application/json": {"example": ...}}. Inclua as respostas de erro que a API realmente usa, com o corpo de erro.
- "components.securitySchemes" com um único esquema: {"type": "http", "scheme": "bearer"}, {"type": "http", "scheme": "basic"} ou {"type": "apiKey", "name": "...", "in": "header"}; e "security" na raiz apontando para ele. Se a API for pública, omita os dois.
- "components.schemas" com os objetos principais.

Regras:
- Não invente endpoints, campos nem códigos. O que faltar vai para "info.description", em uma lista chamada Pendências.
- Exemplos realistas e fictícios: nunca tokens, senhas, documentos ou e-mails reais.
- Os exemplos de resposta usam os mesmos nomes de campo dos schemas.

Informações da API:
[cole o resultado do prompt 1, 2 ou 4, a documentação existente ou a sua descrição]

4. Transformar chamadas reais em documentação

Quando você só tem chamadas que funcionam. No navegador, abra as ferramentas de desenvolvedor, aba Rede, clique com o botão direito na requisição e use “Copiar como cURL”.

Abaixo há chamadas reais a uma API, em cURL, com as respostas que voltaram.
Já troquei tokens e dados pessoais por valores fictícios.

[cole cada cURL seguido do código de status e do corpo da resposta]

Faça:
1. Agrupe as chamadas por recurso e deduza os endpoints: método e caminho, trocando valores que variam por {parâmetros} com nomes claros (por exemplo /pedidos/123 vira /pedidos/{id}).
2. Para cada endpoint, liste parâmetros de caminho, consulta e cabeçalho, com tipo e um exemplo tirado das chamadas.
3. Use os corpos reais como exemplos de requisição e de resposta, encurtando listas longas para dois itens.
4. Identifique a autenticação pelos cabeçalhos (Authorization, X-API-Key ou outro), sem repetir o valor.
5. Marque como “visto uma vez” o que aparece em uma só chamada, e liste o que falta saber: respostas de erro não observadas, parâmetros opcionais e limites.

Entregue em tabelas, prontas para usar no prompt 3.

5. Revisar a documentação

Uma segunda leitura antes de publicar. Use o arquivo de Exportar ▾ → Markdown ou OpenAPI 3.

Revise a documentação de API abaixo como alguém que vai integrar com ela pela primeira vez.

[cole o Markdown ou o OpenAPI exportado pelo API Docs]

Verifique e aponte, endpoint por endpoint:
- Método coerente com a ação: GET só lê, POST cria, PUT substitui, PATCH altera parte, DELETE remove.
- Caminhos com substantivos e padrão de nomes consistente (plural ou singular, maiúsculas, hífens).
- Parâmetros sem descrição, sem exemplo, com tipo errado, ou de caminho que não aparecem no caminho.
- Respostas de erro ausentes (400, 401, 403, 404, 422, 500) e erros devolvidos com código 200.
- Exemplos que não batem com o schema ou entre si.
- Dados que parecem reais ou sensíveis em exemplos: tokens, senhas, documentos, e-mails.
- Resumos vagos e descrições que não dizem o efeito da operação.

Entregue uma tabela com: endpoint, problema, gravidade (alta, média, baixa) e a correção sugerida, em texto pronto para colar no app. Termine com as três correções mais importantes.

6. Escrever textos para quem vai integrar

Melhora resumos e descrições sem mudar o contrato. A saída vem no formato dos campos do app.

Reescreva os textos desta documentação de API para quem vai integrar com ela.

[cole o Markdown exportado ou a lista de endpoints com resumo e descrição]

Para cada endpoint, entregue:
- Resumo: até 60 caracteres, começando por verbo no infinitivo (por exemplo, Consultar um CEP).
- Descrição: até 4 frases. O que a operação faz, quando usar, efeitos colaterais e um cuidado importante. Use só este Markdown: **negrito**, `código`, links e listas com "- ".
- Descrição de cada parâmetro: uma frase com o formato esperado e um exemplo.

Escreva também a descrição geral da API, com: para que serve, como autenticar, onde conseguir a credencial e um primeiro passo.

Não altere métodos, caminhos, nomes de campos nem códigos. Se um texto atual estiver errado em relação ao contrato, aponte em separado.

7. Ampliar os testes em Python

O arquivo de Exportar ▾ → Testes Python cobre o caminho feliz. Este prompt acrescenta os casos de erro e de borda.

Abaixo está um arquivo de testes pytest gerado a partir da documentação de uma API, e a documentação.

Testes:
[cole o test_*.py exportado]
Documentação:
[cole o OpenAPI ou o Markdown exportado]

Acrescente testes, sem mudar os que existem:
- Para cada endpoint: parâmetro obrigatório ausente, tipo errado, valor fora do limite e recurso inexistente, esperando os códigos que a documentação define.
- Para endpoints com autenticação: sem credencial (401) e, se a documentação definir, sem permissão (403).
- Para listas paginadas: primeira página, página vazia e tamanho máximo.

Regras:
- Reaproveite a fixture api e as funções url, check_status, json_of e assert_shape do arquivo.
- Leia URL e credenciais das variáveis de ambiente já usadas; nunca escreva segredos no código.
- Marque com @WRITE todo teste que use POST, PUT, PATCH ou DELETE.
- Se a documentação não disser qual código esperar, não invente: crie o teste com pytest.skip e o motivo.

Entregue só o código novo, pronto para colar no fim da classe correspondente, e uma lista do que ficou sem teste.

8. Diagnosticar uma chamada que falhou

Para quando o painel de teste mostra erro e você não sabe se o problema é a API, a rede, o navegador ou a documentação.

Uma chamada a uma API falhou. Ajude a descobrir a causa.

Mensagem no navegador: [por exemplo: Failed to fetch, ou o código e o corpo mostrados]
Comando curl (sem o token): [cole o curl copiado do painel Testar requisição]
Resultado do curl no terminal: [código de status, cabeçalhos e corpo, ou a mensagem de erro]
O que a documentação diz que deveria acontecer: [código e corpo esperados]

Classifique a causa mais provável entre: bloqueio de CORS no navegador, rede ou DNS, certificado HTTPS, credencial ausente ou expirada, falta de permissão, requisição malformada, recurso inexistente, erro do servidor, ou documentação desatualizada.

Explique em que evidência você se baseou, diga o próximo teste que confirma a hipótese e, se for o caso, o que corrigir na documentação. Não suponha nada que as evidências não mostrem.

9. Implementar a classe gerada para o InterSystems IRIS

A exportação InterSystems IRIS cria rotas e métodos com a resposta de exemplo e marcas TODO. Este prompt pede a implementação, mantendo o contrato.

Abaixo está uma classe ObjectScript que estende %CSP.REST, gerada a partir da documentação de uma API. Cada método devolve a resposta de exemplo e tem um comentário TODO.

Classe:
[cole o .cls exportado]
Regras de negócio e dados:
[descreva as tabelas ou classes persistentes envolvidas e o que cada endpoint deve fazer]

Implemente os métodos marcados com TODO:
- Não mude o UrlMap, os nomes dos métodos nem os códigos e campos da documentação.
- Use %DynamicObject e %DynamicArray para montar o JSON de resposta.
- Em SQL, use parâmetros (? ou :variável); nunca concatene texto do usuário na consulta.
- Responda com ..Erro(código, mensagem) nos erros documentados: 400 para entrada inválida e 404 para recurso inexistente.
- Mantenha o bloco Try/Catch existente.

Entregue a classe completa e, em seguida, a lista de suposições que você fez sobre os dados.

Como importar o JSON do prompt 3

1. Copie a resposta da IA para um editor de texto e salve com a extensão .json, por exemplo minha-api.json.
2. No app, use Importar ▾ → Swagger / OpenAPI, ou arraste o arquivo para a janela. Se já houver endpoints, escolha Mesclar ou Substituir tudo.
3. Passe pelo modo Editar: confira caminhos, parâmetros e exemplos, e leia as pendências na descrição geral.
4. No modo Visualizar, teste cada endpoint em Testar requisição. Onde a resposta real divergir do exemplo, vale a resposta real.
5. Clique em Salvar.

Para APIs grandes, peça um JSON por tag e importe cada um com Mesclar: o app acrescenta o que é novo e ignora endpoints com o mesmo método e caminho.

Erros comuns

• “Failed to fetch: a API caiu”

  Quase sempre é CORS ou rede. Rode o curl antes de concluir qualquer coisa.

• Credencial no exemplo ou na descrição

  O arquivo HTML é feito para ser enviado. Token e senha vão só nos campos do painel de teste, que não são gravados.

• Exemplo inventado

  Um exemplo escrito de cabeça diverge da API real. Execute a chamada e use a resposta verdadeira como exemplo.

• Documentar só o sucesso

  Quem integra precisa saber o que volta quando dá errado. Documente 400, 401, 404 e o corpo de erro.

• Corpo em GET

  Conteúdo em GET não tem significado definido no HTTP. Para filtros, use parâmetros de consulta.

• Esquecer de salvar

  Enquanto aparecer “● não salvo”, nada foi gravado. Use Ctrl+S.

Limitações e solução de problemas

O app cobre o essencial do OpenAPI, não a especificação inteira. O que fica de fora:

• Uma única forma de autenticação para a API toda. Não há autenticação por endpoint, OAuth 2 com fluxos, nem mais de um esquema. Ao importar, só o primeiro esquema é aproveitado, e OAuth 2 vira Bearer.
• Parâmetros têm só tipo, sem formato, lista de valores, mínimo ou máximo.
• Exemplos de resposta são exportados sempre como application/json, e cabeçalhos de resposta não são documentados.
• Os schemas ficam numa lista própria; os endpoints não apontam para eles com $ref.
• Na importação, ficam de fora os parâmetros formData do Swagger 2.0 e os cabeçalhos de resposta; de várias tags ou vários exemplos, fica o primeiro.
• O YAML é lido por um interpretador próprio, que cobre o uso comum. Se um arquivo YAML falhar, converta-o para JSON e importe de novo.

Revisão rápida

Tente responder antes de abrir cada pergunta.

Referências

1. Giovani Perotto Mesquita, “API Docs”, aplicativo em um único arquivo HTML, giovanipm.github.io/api-docs.html.
2. Roy Thomas Fielding (em inglês), “Architectural Styles and the Design of Network-based Software Architectures”, tese de doutorado, Universidade da Califórnia em Irvine, 2000, capítulo 5, acesso em 11/11/2026, ics.uci.edu/~fielding/pubs/dissertation/top.htm.
3. IETF (em inglês), RFC 9110, “HTTP Semantics”, junho de 2022, seções 9 (métodos) e 15 (códigos de status), acesso em 11/11/2026, rfc-editor.org/rfc/rfc9110.
4. IETF (em inglês), RFC 3986, “Uniform Resource Identifier (URI): Generic Syntax”, 2005, acesso em 11/11/2026, rfc-editor.org/rfc/rfc3986.
5. IETF (em inglês), RFC 8259, “The JavaScript Object Notation (JSON) Data Interchange Format”, 2017, acesso em 11/11/2026, rfc-editor.org/rfc/rfc8259.
6. IETF (em inglês), RFC 7617, “The 'Basic' HTTP Authentication Scheme”, 2015, acesso em 11/11/2026, rfc-editor.org/rfc/rfc7617.
7. IETF (em inglês), RFC 6750, “The OAuth 2.0 Authorization Framework: Bearer Token Usage”, 2012, acesso em 11/11/2026, rfc-editor.org/rfc/rfc6750.
8. OpenAPI Initiative (em inglês), “OpenAPI Specification v3.0.3”, 20/02/2020, inclusive o apêndice A, “Revision History”, acesso em 11/11/2026, spec.openapis.org/oas/v3.0.3.html.
9. OpenAPI Initiative (em inglês), “OpenAPI Specification v3.2.0”, setembro de 2025, acesso em 11/11/2026, spec.openapis.org/oas/v3.2.
10. Wikipédia (em inglês), “OpenAPI Specification”, acesso em 11/11/2026, en.wikipedia.org/wiki/OpenAPI_Specification. Divergência: a Wikipédia data a criação do Swagger em 2010 e o anúncio da OpenAPI Initiative em novembro de 2015; o histórico de revisões da especificação [8] registra a versão 1.0 em 10/08/2011 e a doação em 31/12/2015.
11. MDN Web Docs (em inglês), “Cross-Origin Resource Sharing (CORS)”, acesso em 11/11/2026, developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS.
12. ViaCEP, página do webservice, acesso em 11/11/2026, viacep.com.br. Divergência: a página mostra "erro": true para CEP inexistente; a chamada real deste tutorial, em 11/11/2026, devolveu "erro": "true".
13. Postman (em inglês), “Postman Collection Format v2.1.0”, esquema JSON, acesso em 11/11/2026, schema.getpostman.com/json/collection/v2.1.0/collection.json.
14. pytest (em inglês), documentação, acesso em 11/11/2026, docs.pytest.org.
15. Requests (em inglês), “Requests: HTTP for Humans”, documentação, acesso em 11/11/2026, requests.readthedocs.io.
16. InterSystems (em inglês), “Creating REST Services”, documentação do InterSystems IRIS, acesso em 11/11/2026, docs.intersystems.com/irislatest/csp/docbook/Doc.View.cls?KEY=GREST.
17. MDN Web Docs (em inglês), “File System API”, acesso em 11/11/2026, developer.mozilla.org/en-US/docs/Web/API/File_System_API.
18. IETF (em inglês), RFC 5789, “PATCH Method for HTTP”, 2010, acesso em 11/11/2026, rfc-editor.org/rfc/rfc5789.

What API Docs is

API Docs is an editor and viewer for REST API documentation in a single HTML file. ^[1] It shows an API's endpoints, lets you try them in the browser and exports the documentation to OpenAPI, Postman, Python tests, InterSystems IRIS, Markdown and PDF. The data is stored inside the file itself: to share the documentation, you just send the HTML.

Open API Docs →

This tutorial has two halves. The first explains the theory behind each field on the screen: what an API is, what an HTTP request looks like, what status codes mean, how authentication works and why the OpenAPI standard exists. The second is a hands-on walkthrough: you will document and test a real public API, ViaCEP, a Brazilian postcode (CEP) lookup service, and export the result. At the end, ready-to-copy AI prompts speed up each step.

What you need

• A current browser. Chrome and Edge write straight to the file; in other browsers, saving downloads a copy.
• An internet connection only for trying requests and importing from a URL. Viewing, editing, importing a file and exporting work offline.
• No prior programming knowledge. Programmers will get more out of the export sections.

What an API is

API stands for Application Programming Interface. It is a contract between two programs: one, the server, offers functions; the other, the client, asks for them following agreed rules. A delivery app that fills in the address from a postcode does not hold the country's postcode database: it asks an API and gets the answer ready-made.

The contract says what can be asked for, how to ask and what comes back. It does not say how the server does the work internally. That is what lets you change the server's database or language without breaking clients, as long as the contract stays the same. Documenting an API means writing that contract so that people and programs can read it.

REST

Most web APIs follow, more or less closely, the REST style (Representational State Transfer), described by Roy Fielding in his 2000 doctoral dissertation. ^[2] Fielding defines REST as a set of architectural constraints. The ones you meet most often are:

• Separate client and server. Each side evolves without depending on the other.
• Stateless. Each request carries everything the server needs to handle it, including the credential. The server does not “remember” the previous exchange.
• Cache. The response says whether it can be reused, which saves trips to the server.
• Uniform interface. Everything is a resource identified by an address (the address for a postcode, a customer's order list), and operations on it use the same few HTTP verbs.

In practice, “REST API” usually means an API that uses HTTP, organises addresses around resources and exchanges data as JSON. API Docs documents exactly this kind of API.

Anatomy of a request

Client and server talk over HTTP. Each exchange is a pair: the client sends a request and the server returns a response. The meaning of each part is set by RFC 9110, the current standard for HTTP semantics. ^[3]

The URL: server, path and parameters

A resource's address is a URL, whose syntax is defined by RFC 3986. ^[4] In API Docs, the URL is built from three fields you fill in separately:

Server (base URL)

The start shared by every address, such as https://api.correios.com.br. An API may have several: production, staging, local.

Path

The resource within the server, such as /cep/v2/enderecos/{cep}. Braces mark a variable part.

Path parameter

The value that replaces the braces. It identifies which resource: 01001001. It is always required.

Query parameter

name=value pairs after the ?, separated by &. They filter, sort or paginate: ?uf=SP&size=50. They are usually optional.

Header

Information about the request outside the URL: accepted format (Accept), credential (Authorization), language.

Cookie

A value the browser stores and sends back to the same server. Rare in APIs used by other systems.

These four places are exactly the options in the Local (location) column of the app's parameters: path, query, header and cookie.

Methods

The method says what to do with the resource. RFC 9110 classifies methods by two properties that affect safety and retries: a safe method is, by definition, read-only; an idempotent one is where repeating the same request has the same effect as making it once. ^[3]

Why it matters: if the network drops in the middle of a PUT, the client can safely retry; retrying a POST may create two orders. That is why the tests the app exports do not run data-changing methods unless you allow it.

The body and JSON

POST, PUT and PATCH requests carry data in the body. The Content-Type header states the format; in REST APIs it is almost always application/json. JSON is a text format with objects in braces, lists in brackets, strings in quotes, numbers and the values true, false and null, defined by RFC 8259. ^[5]

{
  "numero": "9912345678",
  "dr": 10
}

A GET request should not carry a body: RFC 9110 says content in a GET has no defined meaning. ^[3] That is why the app does not show the body field for GET and HEAD.

Responses and status codes

Every response starts with a three-digit code. The first digit gives the class, and the app uses it to colour the response badges. ^[3]

The split between 4xx and 5xx says whose fault it is and therefore who needs to act. Good documentation also lists the error responses, with an example body, because that is where the client developer most needs help.

Authentication

Most APIs need to know who is asking. Because REST is stateless, the credential goes in every request, usually in the Authorization header. The app offers the four most common schemes under Editar → Autenticação (Edit → Authentication):

In the app, authentication applies to every endpoint. When trying requests, the credential fields appear in the Testar requisição (try request) panel. They stay in memory only and are not written to the file on save.

Documenting with OpenAPI

Free-text documentation works for people but not for programs. The OpenAPI Specification solves this: it defines a standard, language-agnostic description of HTTP APIs that people and computers can read without access to the source code. ^[8] An OpenAPI document is a JSON object, which may be written in JSON or in YAML. ^[8]

A little history

The format began as Swagger, at the company Wordnik. Wikipedia places its creation in 2010; the specification's own revision history records version 1.0 on 10 August 2011 and Swagger 2.0 on 8 September 2014. ^{[10] [8]} In 2015 the specification was donated to the OpenAPI Initiative, under the Linux Foundation, and renamed OpenAPI. The donation date differs between sources: Wikipedia cites the initiative's announcement in November 2015, and the specification's history records the donation on 31 December 2015. Version 3.0.0 came out on 26 July 2017, and 3.0.3, the one the app exports, on 20 February 2020. ^[8] Newer versions exist: 3.2.0 was published in September 2025. ^[9] The Swagger name lives on in SmartBear's tools, such as Swagger UI, which is why people still say “the API's Swagger”.

Why a standard helps

• One source, many uses. The same file produces the documentation page, collections for testing tools, clients in several languages and server skeletons.
• Contract before code. In the design-first style, the team writes and discusses the specification before coding, and client and server can be built in parallel. In the code-first style, the specification is generated from finished code. API Docs serves the first style and also imports the output of the second.
• Checkable. An OpenAPI document can be validated by a program, and tests can check that the real API does what is written.

Where each field of the app ends up

Each field in the app maps to a part of the exported OpenAPI document. Knowing the mapping helps you read any OpenAPI file you come across.

Schemas describe the shape of an object: which fields it has and of what type. OpenAPI 3.0 uses an extended subset of JSON Schema for this. ^[8]

First steps with the sample

The file comes with sample documentation, “API Busca CEP — Correios”, a postcode lookup API from the Brazilian postal service. It shows how a complete API looks in the app: token authentication, a token endpoint, a lookup, a paginated search and a schema. The sample's own description warns that paths and fields must be checked on the official Correios portal before any real use. ^[1] In five minutes:

1. Open API Docs. It starts in Visualizar (view) mode, on the overview: title, version, description, server and authentication type.
2. In the sidebar, click GET /cep/v2/enderecos/{cep}. The endpoint card opens with the description, the parameter table and the responses. The red asterisk next to cep marks a required parameter.
3. Note the colours: GET blue, POST green; 2xx responses green, 4xx orange and 5xx red.
4. In the Filtrar endpoints… (filter endpoints) field, type token. Only the authentication endpoint remains. Clear the filter.
5. At the bottom of the sidebar, under Schemas, click Endereco (address). The object definition appears as JSON.

At the end of each open card is the Testar requisição panel. Do not use it with the Correios sample: that API needs a contract and a token. The real test comes in the next section, with an open API.

Your first document: ViaCEP

ViaCEP is a free Brazilian postcode lookup service that needs no sign-up. A lookup is a GET on viacep.com.br/ws/{cep}/json/, with the postcode as 8 digits. ^[12] The walkthrough below was run with real clicks in the app on 11 November 2026. The texts typed into the app stay in Portuguese, as in the screenshots; the English meaning is in brackets.

1. Start a blank document

1. If you want to keep the sample, save a copy of the file first.
2. Click Novo (new) and confirm. The app switches to Editar (edit) mode, on the Informações gerais (general information) page.

2. Fill in the general information

1. Título (title): ViaCEP. Versão (version): 1.0. The version is your documentation's; when the contract changes, raise it.
2. Descrição (description): a paragraph about the API. The field accepts simple Markdown: **bold**, `code`, links and lists with “- ”.
3. Under Servidores (servers), change the base URL to https://viacep.com.br, with no trailing slash, and the description to Produção (production).

Authentication stays at Nenhuma (none), which is already the default for a new document.

3. Create the endpoint

1. In the sidebar, click + Endpoint. A GET /novo-recurso appears.
2. Caminho (path): /ws/{cep}/json/. Resumo (summary): Consultar um CEP [look up a postcode]. Tag: CEP. The tag groups endpoints in the sidebar.
3. Click Detectar {parâmetros} do caminho (detect path parameters). The app reads the braces in the path and creates the cep parameter, location path, required.
4. On the parameter row, type the description CEP com 8 dígitos, sem hífen [8-digit postcode, no hyphen] and the example 01001000. The example is the value the try panel starts with.

4. Document the responses

1. In the existing 200 response, type the description: Endereço encontrado. CEP inexistente também volta 200, com o campo `erro`. [Address found. A non-existent postcode also returns 200, with the erro field.]
2. In Exemplo de resposta (response example), paste a short JSON and click Formatar JSON (format JSON):

   {"cep":"01001-000","logradouro":"Praça da Sé","complemento":"lado ímpar","bairro":"Sé","localidade":"São Paulo","uf":"SP","ddd":"11"}

   If the JSON is wrong, the box turns red with the notice “JSON inválido” (invalid JSON).
3. Click + Resposta (add response), type the code 400 and the description Formato inválido (não tem 8 dígitos). [Invalid format (not 8 digits).]

5. Test it for real

1. Click Visualizar (view) and, in the sidebar, GET /ws/{cep}/json/.
2. In the Testar requisição panel, the cep field already holds 01001000, and the full URL appears next to the button.
3. Click Executar (run). In this tutorial's test, 200 OK arrived in under a second with the address of Praça da Sé.

Compare the real response with the example you wrote: it has extra fields. That is common, and it is why the exported tests only check that the documented fields exist, not that the response is identical. For complete documentation, copy the real response into the example.

6. Provoke an error

1. Change the postcode to 0100100, with 7 digits, and run. The app shows Falha na requisição (request failed): “Failed to fetch”.
2. Change it to 99999999 and run. Back comes 200 OK with {"erro": "true"}.

The first case looks like the API is down, but it is not. The Trying requests and CORS section explains what happened. In the second, ViaCEP's documentation shows "erro": true, a boolean, and the real response held "true", a string. ^[12] This kind of mismatch is exactly what testing the documentation reveals.

7. Save and export

1. Click Salvar (save, Ctrl+S) and store it, for instance, as viacep.html. That file is already finished documentation, ready to send.
2. Under Exportar ▾ → OpenAPI 3 (export), the app downloads viacep-openapi.json. In this tutorial's test, the file passed validation by the @apidevtools/swagger-parser package, which checks the document against the official OpenAPI 3.0 schema.
3. Under Exportar ▾ → Testes Python (Python tests), the app downloads test_viacep.py. Run with pytest, the test passed against the real ViaCEP.

The interface

Top bar

The API title and version, the ● não salvo (not saved) notice, the Visualizar / Editar (view / edit) switch, and the Salvar, Exportar ▾, Importar ▾ and Novo buttons.

Sidebar

The Filtrar endpoints… field, which searches the method, path, summary and tag; the endpoints grouped by tag; and the schemas. In edit mode it adds Informações gerais, Autenticação, Tags, + Endpoint and + Schema.

Main area

In view mode, the browsable documentation with a try panel on each endpoint. In edit mode, the form for the item chosen in the sidebar.

Notices

Short messages appear for a few seconds at the bottom of the screen: file saved, parameters detected, import error.

On screens narrower than 860 px, the sidebar disappears and navigation is by scrolling the main area only.

Button names

Edit mode in detail

Parameters

Each row has a name, location (path, query, header, cookie), type, the required mark, description and example. A path parameter is always required: the OpenAPI specification demands it, and the app enforces the rule on export even if the mark is off. ^[8] The types integer, number and boolean make the example export as a number or boolean, not as text.

Body and responses

The Content-Type field suggests the most common types. JSON example fields validate as you type and have the Formatar JSON button. An example that is not JSON is accepted but treated as text.

Endpoints marked deprecated appear struck through, with an “obsoleto” badge. It is the standard way to warn that something will go, without removing it suddenly.

Trying requests and CORS

The Testar requisição panel builds the URL from the chosen server, fills the parameters with the examples, adds the credential you typed and sends the request from the browser itself. The result shows the code, the time, the response headers, the equivalent curl command and the formatted body.

Why the browser blocks some calls

For security, the browser only lets a script read a response from another site if that site allows it, with the Access-Control-Allow-Origin header. This mechanism is called CORS (Cross-Origin Resource Sharing). ^[11] Without that permission, the browser hands the script only a generic error, and the app shows “Failed to fetch”.

That is what happened with the 7-digit postcode. Called outside the browser, ViaCEP answered 400 Bad Request with an HTML page and without the CORS header; the valid lookup came back with Access-Control-Allow-Origin: *. The error was there, but the browser hid it.

In addition, requests with Authorization, with Content-Type: application/json or with methods such as PUT and DELETE are first preceded by an OPTIONS query, the preflight, which the server must also approve. ^[11] Many corporate APIs do not open CORS to any origin.

What to do when a try fails

1. Open Comando curl, click Copiar curl (copy curl) and run it in a terminal. curl is not a browser and does not apply CORS: you see the real code and body.
2. If curl works, the API is up and the block is the browser's. Document as usual; it is only the in-app try that is not possible.
3. If curl fails too, check the server, path, credential and network.

Saving

The app uses no server and no database. The documentation sits in a JSON block inside the HTML itself, and saving means writing a new HTML with that block updated.

What is not written: the credentials typed for trying, the values changed in the try panel and the results of the calls. If you try to close the tab with pending changes, the browser asks for confirmation.

Importing

Many APIs already have a specification, generated by the server's own framework. Importing saves you from typing it all again.

If the current document already has endpoints, the app asks what to do:

• Mesclar (merge) adds endpoints, tags, servers and schemas that do not exist yet. An endpoint with the same method and path as an existing one is skipped. In the test, merging ViaCEP into the Correios sample gave 5 endpoints.
• Substituir tudo (replace all) discards the current documentation.

When the source specification has no example, the app builds one from the schema, with generic values such as "string" and 0. Review these examples after importing.

Exporting

The Python tests

The generated file starts with installation and run instructions (in Portuguese). Each test calls an endpoint with the example values, checks the documented success code and verifies that the fields of the example response exist in the real response with the same JSON type.

pip install pytest requests
pytest -v test_viacep.py

• The base URL and credentials come from environment variables: API_BASE_URL, API_TOKEN, API_USER and API_PASS, or API_KEY. That way no password sits in the code.
• Data-changing methods (POST, PUT, PATCH, DELETE) only run with API_ALLOW_WRITE=1. Without it, they show as skipped.
• If the API has authentication and the endpoint documents a 401 response, the app also creates a test without credentials that expects 401.
• API_MAX_MS sets a maximum response time, if you want to watch for slowness.

AI prompts

An AI speeds up the slow parts of documentation: finding endpoints scattered through the code, turning loose calls into a specification, writing descriptions and extending tests. It also makes confident mistakes: it invents fields, guesses status codes and describes behaviour the API does not have. Treat its output as a draft and check each endpoint with the Testar requisição (try request) panel, which talks to the real API. To write better prompts, see the prompt tutorial.

Before pasting: remove tokens, passwords, API keys, internal addresses and customer data from what goes to the AI. Replace them with made-up values and follow your organisation's policy. The app only talks to the API you are testing, but the AI service receives everything you paste into it.

Replace the parts in brackets and paste into the AI tool you use. The prompts follow the order of the work: 1 to 4 produce the documentation, and 5 to 9 review it and put it to use. Each one works on its own. The app's field names stay in Portuguese, as on screen.

1. Interview before documenting

When the API still lives in the head of whoever built it. The AI asks instead of assuming.

You are a technical writer experienced in REST APIs and the OpenAPI specification.
I want to document this API: [describe in a few sentences what it does and who uses it].

Before writing any documentation, interview me:
- Ask one question at a time and wait for my answer.
- Cover: the base URL of each environment; the authentication method; each resource and the operations on it (method and path); path, query and header parameters, with type, whether required and an example; request bodies; success and error responses, with the code and an example body; pagination; usage limits; what is deprecated.
- Ask mostly about errors: what happens with invalid data, with no credential, with no permission and with a resource that does not exist.
- Do not invent answers. If I do not know, record it as an open item.

At the end, deliver: a table of endpoints (method, path, summary, tag), the parameters and responses of each, example bodies in JSON and the list of open items.

2. Find the endpoints in the code

For APIs that are already built but undocumented. It asks for the source of each item, which makes checking easier.

From the code below, work out the contract of the REST API it implements.

Language and framework: [for example: Java with Spring, C# with ASP.NET, Node with Express, Python with FastAPI, ObjectScript with %CSP.REST]
Code:
[paste the controllers, routes or UrlMap, and the input and output classes]

Deliver:
1. Table of endpoints: method, path (with {parameters}), summary, suggested tag and the file and line it came from.
2. For each endpoint: parameters (name, location path, query, header or cookie, type, required), the request body with a JSON example, and responses with code and example body.
3. The error codes the code actually returns, and in which situation.
4. How authentication is checked.
5. Gaps: returns that depend on code not shown here, unhandled exceptions and ambiguous behaviour, with a question for each.

Do not infer what the code does not show. Use made-up examples.

3. Generate the OpenAPI to import into the app

Turns what you gathered into a file the app imports in one go, instead of typing endpoint by endpoint. The format requested is what the app's importer uses.

Generate an OpenAPI 3.0.3 specification in JSON for the API described at the end. It will be imported into API Docs, an editor that reads a subset of OpenAPI.

Reply with the JSON only, no comments and no code fences.

Use only these elements:
- "openapi": "3.0.3" and "info" with "title", "version" and "description". The description accepts simple Markdown: **bold**, `code`, links and lists with "- ".
- "servers": a list with "url" (no trailing slash) and "description".
- "tags": a list with "name" and "description". Each operation uses a single tag.
- "paths": one operation per method (get, post, put, patch, delete), with "tags", "summary" (short, starting with a verb), "description" and, where relevant, "deprecated": true.
- "parameters": "name", "in" (path, query, header or cookie), "required", "description", "schema" with "type" (string, integer, number, boolean, array or object) and "example". Every {parameter} in the path needs a parameter with "in": "path" and "required": true.
- "requestBody" only on post, put and patch: "description" and "content" with a single media type, usually "application/json", containing "example".
- "responses": for each code, "description" and, when there is a body, "content": {"application/json": {"example": ...}}. Include the error responses the API actually uses, with the error body.
- "components.securitySchemes" with a single scheme: {"type": "http", "scheme": "bearer"}, {"type": "http", "scheme": "basic"} or {"type": "apiKey", "name": "...", "in": "header"}; and "security" at the root pointing to it. If the API is public, leave both out.
- "components.schemas" with the main objects.

Rules:
- Do not invent endpoints, fields or codes. Whatever is missing goes into "info.description", in a list called Open items.
- Realistic, made-up examples: never real tokens, passwords, ID numbers or e-mail addresses.
- Response examples use the same field names as the schemas.

API information:
[paste the result of prompt 1, 2 or 4, the existing documentation or your description]

4. Turn real calls into documentation

When all you have is calls that work. In the browser, open the developer tools, Network tab, right-click the request and use “Copy as cURL”.

Below are real calls to an API, as cURL, with the responses that came back.
I have already replaced tokens and personal data with made-up values.

[paste each cURL followed by the status code and the response body]

Do this:
1. Group the calls by resource and infer the endpoints: method and path, replacing values that vary with clearly named {parameters} (for example /orders/123 becomes /orders/{id}).
2. For each endpoint, list path, query and header parameters, with type and an example taken from the calls.
3. Use the real bodies as request and response examples, shortening long lists to two items.
4. Identify the authentication from the headers (Authorization, X-API-Key or another), without repeating the value.
5. Mark as “seen once” whatever appears in a single call, and list what is still unknown: unobserved error responses, optional parameters and limits.

Deliver it as tables, ready to use in prompt 3.

5. Review the documentation

A second reading before publishing. Use the file from Exportar ▾ → Markdown or OpenAPI 3.

Review the API documentation below as someone integrating with it for the first time.

[paste the Markdown or OpenAPI exported by API Docs]

Check and point out, endpoint by endpoint:
- A method that matches the action: GET only reads, POST creates, PUT replaces, PATCH changes part, DELETE removes.
- Paths made of nouns with a consistent naming pattern (plural or singular, case, hyphens).
- Parameters with no description, no example, the wrong type, or path parameters that do not appear in the path.
- Missing error responses (400, 401, 403, 404, 422, 500) and errors returned with code 200.
- Examples that do not match the schema or each other.
- Data in examples that looks real or sensitive: tokens, passwords, ID numbers, e-mail addresses.
- Vague summaries and descriptions that do not state the effect of the operation.

Deliver a table with: endpoint, problem, severity (high, medium, low) and the suggested fix, as text ready to paste into the app. End with the three most important fixes.

6. Write texts for integrators

Improves summaries and descriptions without changing the contract. The output comes in the shape of the app's fields.

Rewrite the texts of this API documentation for people who will integrate with it.

[paste the exported Markdown or the list of endpoints with summary and description]
Language of the texts: [for example: Portuguese, English]

For each endpoint, deliver:
- Summary: up to 60 characters, starting with a verb (for example, Look up a postcode).
- Description: up to 4 sentences. What the operation does, when to use it, side effects and one important caveat. Use only this Markdown: **bold**, `code`, links and lists with "- ".
- Description of each parameter: one sentence with the expected format and an example.

Also write the general description of the API, with: what it is for, how to authenticate, where to get the credential and a first step.

Do not change methods, paths, field names or codes. If a current text is wrong with respect to the contract, point it out separately.

7. Extend the Python tests

The file from Exportar ▾ → Testes Python covers the happy path. This prompt adds error and edge cases.

Below is a pytest test file generated from an API's documentation, and the documentation.

Tests:
[paste the exported test_*.py]
Documentation:
[paste the exported OpenAPI or Markdown]

Add tests, without changing the existing ones:
- For each endpoint: missing required parameter, wrong type, out-of-range value and non-existent resource, expecting the codes the documentation defines.
- For endpoints with authentication: no credential (401) and, if the documentation defines it, no permission (403).
- For paginated lists: first page, empty page and maximum size.

Rules:
- Reuse the api fixture and the url, check_status, json_of and assert_shape functions from the file.
- Read the URL and credentials from the environment variables already used; never write secrets into the code.
- Mark with @WRITE every test that uses POST, PUT, PATCH or DELETE.
- If the documentation does not say which code to expect, do not invent one: create the test with pytest.skip and the reason.

Deliver only the new code, ready to paste at the end of the matching class, and a list of what is still untested.

8. Diagnose a failed call

For when the try panel shows an error and you do not know whether the problem is the API, the network, the browser or the documentation.

A call to an API failed. Help me find the cause.

Message in the browser: [for example: Failed to fetch, or the code and body shown]
curl command (without the token): [paste the curl copied from the Testar requisição panel]
curl result in the terminal: [status code, headers and body, or the error message]
What the documentation says should happen: [expected code and body]

Classify the most likely cause among: CORS block in the browser, network or DNS, HTTPS certificate, missing or expired credential, lack of permission, malformed request, non-existent resource, server error, or outdated documentation.

Explain which evidence you relied on, give the next test that confirms the hypothesis and, if relevant, what to fix in the documentation. Do not assume anything the evidence does not show.

9. Implement the class generated for InterSystems IRIS

The InterSystems IRIS export creates routes and methods that return the example response, with TODO marks. This prompt asks for the implementation while keeping the contract.

Below is an ObjectScript class extending %CSP.REST, generated from an API's documentation. Each method returns the example response and has a TODO comment.

Class:
[paste the exported .cls]
Business rules and data:
[describe the tables or persistent classes involved and what each endpoint must do]

Implement the methods marked TODO:
- Do not change the UrlMap, the method names or the documented codes and fields.
- Use %DynamicObject and %DynamicArray to build the JSON response.
- In SQL, use parameters (? or :variable); never concatenate user text into the query.
- Reply with ..Erro(code, message) for the documented errors: 400 for invalid input and 404 for a non-existent resource.
- Keep the existing Try/Catch block.

Deliver the complete class and then the list of assumptions you made about the data.

How to import the JSON from prompt 3

1. Copy the AI's answer into a text editor and save it with the .json extension, for example my-api.json.
2. In the app, use Importar ▾ → Swagger / OpenAPI, or drag the file onto the window. If there are already endpoints, choose Mesclar (merge) or Substituir tudo (replace all).
3. Go through Editar (edit) mode: check paths, parameters and examples, and read the open items in the general description.
4. In Visualizar (view) mode, try each endpoint with Testar requisição. Where the real response differs from the example, the real response wins.
5. Click Salvar (save).

For large APIs, ask for one JSON per tag and import each with Mesclar: the app adds what is new and skips endpoints with the same method and path.

Common mistakes

• “Failed to fetch: the API is down”

  It is almost always CORS or the network. Run curl before concluding anything.

• Credentials in an example or description

  The HTML file is made to be sent around. Tokens and passwords belong only in the try panel fields, which are not saved.

• Made-up examples

  An example written from memory drifts from the real API. Make the call and use the real response as the example.

• Documenting only success

  Integrators need to know what comes back when things go wrong. Document 400, 401, 404 and the error body.

• A body in GET

  Content in a GET has no defined meaning in HTTP. For filters, use query parameters.

• Forgetting to save

  While “● não salvo” shows, nothing has been written. Use Ctrl+S.

Limitations and troubleshooting

The app covers the essentials of OpenAPI, not the whole specification. What is left out:

• A single authentication method for the whole API. There is no per-endpoint authentication, no OAuth 2 with flows and no more than one scheme. On import, only the first scheme is used, and OAuth 2 becomes Bearer.
• Parameters have a type only, with no format, list of values, minimum or maximum.
• Response examples are always exported as application/json, and response headers are not documented.
• Schemas are kept in a list of their own; endpoints do not point to them with $ref.
• On import, Swagger 2.0 formData parameters and response headers are dropped; of several tags or several examples, the first is kept.
• YAML is read by the app's own parser, which covers common use. If a YAML file fails, convert it to JSON and import again.

Quick review

Try to answer before opening each question.

References

1. Giovani Perotto Mesquita, “API Docs”, single-file HTML application (interface in Portuguese), giovanipm.github.io/api-docs.html.
2. Roy Thomas Fielding, “Architectural Styles and the Design of Network-based Software Architectures”, doctoral dissertation, University of California, Irvine, 2000, chapter 5, accessed 11 November 2026, ics.uci.edu/~fielding/pubs/dissertation/top.htm.
3. IETF, RFC 9110, “HTTP Semantics”, June 2022, sections 9 (methods) and 15 (status codes), accessed 11 November 2026, rfc-editor.org/rfc/rfc9110.
4. IETF, RFC 3986, “Uniform Resource Identifier (URI): Generic Syntax”, 2005, accessed 11 November 2026, rfc-editor.org/rfc/rfc3986.
5. IETF, RFC 8259, “The JavaScript Object Notation (JSON) Data Interchange Format”, 2017, accessed 11 November 2026, rfc-editor.org/rfc/rfc8259.
6. IETF, RFC 7617, “The 'Basic' HTTP Authentication Scheme”, 2015, accessed 11 November 2026, rfc-editor.org/rfc/rfc7617.
7. IETF, RFC 6750, “The OAuth 2.0 Authorization Framework: Bearer Token Usage”, 2012, accessed 11 November 2026, rfc-editor.org/rfc/rfc6750.
8. OpenAPI Initiative, “OpenAPI Specification v3.0.3”, 20 February 2020, including appendix A, “Revision History”, accessed 11 November 2026, spec.openapis.org/oas/v3.0.3.html.
9. OpenAPI Initiative, “OpenAPI Specification v3.2.0”, September 2025, accessed 11 November 2026, spec.openapis.org/oas/v3.2.
10. Wikipedia, “OpenAPI Specification”, accessed 11 November 2026, en.wikipedia.org/wiki/OpenAPI_Specification. Divergence: Wikipedia dates the creation of Swagger to 2010 and the announcement of the OpenAPI Initiative to November 2015; the specification's revision history [8] records version 1.0 on 10 August 2011 and the donation on 31 December 2015.
11. MDN Web Docs, “Cross-Origin Resource Sharing (CORS)”, accessed 11 November 2026, developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS.
12. ViaCEP (in Portuguese), webservice page, accessed 11 November 2026, viacep.com.br. Divergence: the page shows "erro": true for a non-existent postcode; this tutorial's real call, on 11 November 2026, returned "erro": "true".
13. Postman, “Postman Collection Format v2.1.0”, JSON schema, accessed 11 November 2026, schema.getpostman.com/json/collection/v2.1.0/collection.json.
14. pytest, documentation, accessed 11 November 2026, docs.pytest.org.
15. Requests, “Requests: HTTP for Humans”, documentation, accessed 11 November 2026, requests.readthedocs.io.
16. InterSystems, “Creating REST Services”, InterSystems IRIS documentation, accessed 11 November 2026, docs.intersystems.com/irislatest/csp/docbook/Doc.View.cls?KEY=GREST.
17. MDN Web Docs, “File System API”, accessed 11 November 2026, developer.mozilla.org/en-US/docs/Web/API/File_System_API.
18. IETF, RFC 5789, “PATCH Method for HTTP”, 2010, accessed 11 November 2026, rfc-editor.org/rfc/rfc5789.

Che cos'è API Docs

API Docs è un editor e visualizzatore di documentazione di API REST in un unico file HTML. ^[1] Mostra gli endpoint di un'API, permette di provarli nel browser ed esporta la documentazione in OpenAPI, Postman, test Python, InterSystems IRIS, Markdown e PDF. I dati sono conservati dentro il file stesso: per condividere la documentazione basta inviare l'HTML.

Apri API Docs →

Questo tutorial ha due metà. La prima spiega la teoria dietro ogni campo dello schermo: che cos'è un'API, com'è fatta una richiesta HTTP, che cosa significano i codici di stato, come funziona l'autenticazione e perché esiste lo standard OpenAPI. La seconda è un percorso pratico: documenterai e proverai una vera API pubblica, ViaCEP, un servizio brasiliano di ricerca dei codici postali (CEP), ed esporterai il risultato. Alla fine, prompt di IA pronti da copiare accelerano ogni fase.

Che cosa serve

• Un browser aggiornato. Chrome ed Edge scrivono direttamente nel file; negli altri, salvare scarica una copia.
• Una connessione a internet solo per provare le richieste e importare da URL. Vedere, modificare, importare un file ed esportare funzionano senza rete.
• Nessuna conoscenza di programmazione. Chi programma trarrà più profitto dalle sezioni sull'esportazione.

Che cos'è un'API

API significa Application Programming Interface, interfaccia di programmazione delle applicazioni. È un contratto tra due programmi: uno, il server, offre funzioni; l'altro, il client, le richiede seguendo regole concordate. Un'app di consegne che compila l'indirizzo partendo dal codice postale non possiede l'archivio dei codici del paese: lo chiede a un'API e riceve la risposta pronta.

Il contratto dice che cosa si può chiedere, come chiederlo e che cosa torna indietro. Non dice come il server fa il lavoro al suo interno. È questo che permette di cambiare il database o il linguaggio del server senza rompere i client, purché il contratto resti lo stesso. Documentare un'API significa scrivere quel contratto in modo che persone e programmi possano leggerlo.

REST

La maggior parte delle API del web segue, più o meno fedelmente, lo stile REST (Representational State Transfer), descritto da Roy Fielding nella sua tesi di dottorato del 2000. ^[2] Fielding definisce REST come un insieme di vincoli architetturali. Quelli che si incontrano più spesso sono:

• Client e server separati. Ogni parte evolve senza dipendere dall'altra.
• Senza stato (stateless). Ogni richiesta porta tutto ciò che serve al server per gestirla, compresa la credenziale. Il server non “ricorda” lo scambio precedente.
• Cache. La risposta dice se può essere riutilizzata, risparmiando viaggi al server.
• Interfaccia uniforme. Tutto è una risorsa identificata da un indirizzo (l'indirizzo di un codice postale, l'elenco degli ordini di un cliente), e le operazioni su di essa usano gli stessi pochi verbi HTTP.

In pratica, “API REST” indica di solito un'API che usa HTTP, organizza gli indirizzi per risorse e scambia dati in JSON. API Docs documenta proprio questo tipo di API.

Anatomia di una richiesta

Client e server dialogano tramite HTTP. Ogni scambio è una coppia: il client invia una richiesta e il server restituisce una risposta. Il significato di ogni parte è stabilito dalla RFC 9110, la norma attuale sulla semantica di HTTP. ^[3]

L'URL: server, percorso e parametri

L'indirizzo di una risorsa è un URL, la cui sintassi è definita dalla RFC 3986. ^[4] In API Docs, l'URL è composto da tre campi che compili separatamente:

Server (URL base)

L'inizio comune a tutti gli indirizzi, come https://api.correios.com.br. Un'API può averne diversi: produzione, collaudo, locale.

Percorso

La risorsa dentro il server, come /cep/v2/enderecos/{cep}. Le graffe indicano una parte variabile.

Parametro di percorso (path)

Il valore che prende il posto delle graffe. Identifica quale risorsa: 01001001. È sempre obbligatorio.

Parametro di query

Coppie nome=valore dopo il ?, separate da &. Filtrano, ordinano o paginano: ?uf=SP&size=50. Di solito sono facoltativi.

Intestazione (header)

Informazione sulla richiesta fuori dall'URL: formato accettato (Accept), credenziale (Authorization), lingua.

Cookie

Un valore che il browser conserva e rimanda allo stesso server. Raro nelle API usate da altri sistemi.

Questi quattro posti sono esattamente le opzioni della colonna Local (posizione) dei parametri nell'app: path, query, header e cookie.

I metodi

Il metodo dice che cosa fare con la risorsa. La RFC 9110 classifica i metodi secondo due proprietà che incidono sulla sicurezza e sui nuovi tentativi: un metodo sicuro è, per definizione, di sola lettura; uno idempotente è quello in cui ripetere la stessa richiesta ha lo stesso effetto che farla una volta. ^[3]

Perché conta: se la rete cade a metà di un PUT, il client può ripetere senza timori; ripetere un POST può creare due ordini. Per questo i test esportati dall'app non eseguono i metodi che modificano i dati, a meno che tu non lo autorizzi.

Il corpo e il JSON

Le richieste POST, PUT e PATCH portano dati nel corpo. L'intestazione Content-Type indica il formato; nelle API REST è quasi sempre application/json. JSON è un formato di testo con oggetti tra graffe, elenchi tra quadre, testi tra virgolette, numeri e i valori true, false e null, definito dalla RFC 8259. ^[5]

{
  "numero": "9912345678",
  "dr": 10
}

Una richiesta GET non dovrebbe avere corpo: la RFC 9110 dice che un contenuto in un GET non ha significato definito. ^[3] Per questo l'app non mostra il campo del corpo per GET e HEAD.

Risposte e codici di stato

Ogni risposta inizia con un codice di tre cifre. La prima cifra indica la classe, ed è ciò che l'app usa per colorare i badge delle risposte. ^[3]

La distinzione tra 4xx e 5xx dice di chi è la colpa e quindi chi deve intervenire. Una buona documentazione elenca anche le risposte di errore, con un esempio del corpo, perché è lì che lo sviluppatore del client ha più bisogno di aiuto.

Autenticazione

La maggior parte delle API deve sapere chi sta chiedendo. Poiché REST è senza stato, la credenziale va in ogni richiesta, di solito nell'intestazione Authorization. L'app offre i quattro schemi più comuni in Editar → Autenticação (Modifica → Autenticazione):

Nell'app, l'autenticazione vale per tutti gli endpoint. Quando provi le richieste, i campi della credenziale compaiono nel pannello Testar requisição (prova richiesta). Restano solo in memoria e non vengono scritti nel file al salvataggio.

Documentare con OpenAPI

Una documentazione in testo libero va bene per le persone, ma non per i programmi. La Specifica OpenAPI risolve il problema: definisce una descrizione standard e indipendente dal linguaggio delle API HTTP, che persone e computer possono leggere senza accesso al codice sorgente. ^[8] Un documento OpenAPI è un oggetto JSON, che può essere scritto in JSON o in YAML. ^[8]

Un po' di storia

Il formato è nato come Swagger, presso l'azienda Wordnik. Wikipedia colloca la creazione nel 2010; la cronologia delle revisioni della specifica registra la versione 1.0 il 10 agosto 2011 e Swagger 2.0 l'8 settembre 2014. ^{[10] [8]} Nel 2015 la specifica è stata donata alla OpenAPI Initiative, sotto la Linux Foundation, e ha preso il nome di OpenAPI. La data della donazione diverge tra le fonti: Wikipedia cita l'annuncio dell'iniziativa nel novembre 2015, mentre la cronologia della specifica registra la donazione il 31 dicembre 2015. La versione 3.0.0 è uscita il 26 luglio 2017, e la 3.0.3, quella che l'app esporta, il 20 febbraio 2020. ^[8] Esistono versioni più recenti: la 3.2.0 è stata pubblicata nel settembre 2025. ^[9] Il nome Swagger sopravvive negli strumenti di SmartBear, come Swagger UI, ed è per questo che si dice ancora “lo Swagger dell'API”.

Perché uno standard aiuta

• Una fonte, molti usi. Dallo stesso file escono la pagina di documentazione, le collection per gli strumenti di test, i client in vari linguaggi e gli scheletri di server.
• Il contratto prima del codice. Nello stile design-first, il team scrive e discute la specifica prima di programmare, e client e server possono essere sviluppati in parallelo. Nello stile code-first, la specifica è generata dal codice già pronto. API Docs serve il primo stile e importa anche il risultato del secondo.
• Verificabile. Un documento OpenAPI può essere validato da un programma, e i test possono controllare che l'API reale faccia ciò che è scritto.

Dove finisce ogni campo dell'app

Ogni campo dell'app corrisponde a una parte del documento OpenAPI esportato. Conoscere questa corrispondenza aiuta a leggere qualsiasi file OpenAPI.

Gli schema descrivono la forma di un oggetto: quali campi ha e di che tipo. OpenAPI 3.0 usa a questo scopo un sottoinsieme esteso di JSON Schema. ^[8]

Primi passi con l'esempio

Il file contiene una documentazione di esempio, “API Busca CEP — Correios”, un'API di ricerca dei codici postali delle Poste brasiliane. Mostra come appare un'API completa nell'app: autenticazione con token, un endpoint che genera il token, una ricerca puntuale, una ricerca paginata e uno schema. La descrizione stessa dell'esempio avverte che percorsi e campi vanno verificati sul portale ufficiale delle Correios prima di qualsiasi uso reale. ^[1] In cinque minuti:

1. Apri API Docs. Parte in modalità Visualizar (vedi), sulla panoramica: titolo, versione, descrizione, server e tipo di autenticazione.
2. Nella barra laterale, fai clic su GET /cep/v2/enderecos/{cep}. La scheda dell'endpoint si apre con la descrizione, la tabella dei parametri e le risposte. L'asterisco rosso accanto a cep indica un parametro obbligatorio.
3. Osserva i colori: GET blu, POST verde; risposte 2xx verdi, 4xx arancioni e 5xx rosse.
4. Nel campo Filtrar endpoints… (filtra endpoint), scrivi token. Resta solo l'endpoint di autenticazione. Cancella il filtro.
5. In fondo alla barra laterale, sotto Schemas, fai clic su Endereco (indirizzo). La definizione dell'oggetto appare in JSON.

Alla fine di ogni scheda aperta c'è il pannello Testar requisição. Non usarlo con l'esempio delle Correios: quell'API richiede un contratto e un token. La prova vera arriva nella prossima sezione, con un'API aperta.

Il tuo primo documento: ViaCEP

ViaCEP è un servizio brasiliano gratuito di ricerca dei codici postali che non richiede registrazione. Una ricerca è un GET su viacep.com.br/ws/{cep}/json/, con il codice di 8 cifre. ^[12] Il percorso qui sotto è stato eseguito con clic reali nell'app l'11 novembre 2026. I testi scritti nell'app restano in portoghese, come nelle schermate; il significato italiano è tra parentesi quadre.

1. Inizia un documento vuoto

1. Se vuoi conservare l'esempio, salva prima una copia del file.
2. Fai clic su Novo (nuovo) e conferma. L'app passa alla modalità Editar (modifica), sulla pagina Informações gerais (informazioni generali).

2. Compila le informazioni generali

1. Título (titolo): ViaCEP. Versão (versione): 1.0. La versione è quella della tua documentazione; quando il contratto cambia, aumentala.
2. Descrição (descrizione): un paragrafo sull'API. Il campo accetta Markdown semplice: **grassetto**, `codice`, link ed elenchi con “- ”.
3. In Servidores (server), cambia l'URL base in https://viacep.com.br, senza barra finale, e la descrizione in Produção (produzione).

L'autenticazione resta su Nenhuma (nessuna), che è già il valore predefinito di un documento nuovo.

3. Crea l'endpoint

1. Nella barra laterale, fai clic su + Endpoint. Compare un GET /novo-recurso.
2. Caminho (percorso): /ws/{cep}/json/. Resumo (riepilogo): Consultar um CEP [cerca un codice postale]. Tag: CEP. La tag raggruppa gli endpoint nella barra laterale.
3. Fai clic su Detectar {parâmetros} do caminho (rileva i parametri del percorso). L'app legge le graffe del percorso e crea il parametro cep, posizione path, obbligatorio.
4. Sulla riga del parametro, scrivi la descrizione CEP com 8 dígitos, sem hífen [codice di 8 cifre, senza trattino] e l'esempio 01001000. L'esempio è il valore con cui parte il pannello di prova.

4. Documenta le risposte

1. Nella risposta 200 già presente, scrivi la descrizione: Endereço encontrado. CEP inexistente também volta 200, com o campo `erro`. [Indirizzo trovato. Anche un codice inesistente restituisce 200, con il campo erro.]
2. In Exemplo de resposta (esempio di risposta), incolla un JSON breve e fai clic su Formatar JSON (formatta JSON):

   {"cep":"01001-000","logradouro":"Praça da Sé","complemento":"lado ímpar","bairro":"Sé","localidade":"São Paulo","uf":"SP","ddd":"11"}

   Se il JSON è sbagliato, il riquadro diventa rosso con l'avviso “JSON inválido” (JSON non valido).
3. Fai clic su + Resposta (aggiungi risposta), scrivi il codice 400 e la descrizione Formato inválido (não tem 8 dígitos). [Formato non valido (non ha 8 cifre).]

5. Prova davvero

1. Fai clic su Visualizar (vedi) e, nella barra laterale, su GET /ws/{cep}/json/.
2. Nel pannello Testar requisição, il campo cep contiene già 01001000, e l'URL completo appare accanto al pulsante.
3. Fai clic su Executar (esegui). Nella prova di questo tutorial, 200 OK è arrivato in meno di un secondo con l'indirizzo di Praça da Sé.

Confronta la risposta reale con l'esempio che hai scritto: ha campi in più. È normale, ed è per questo che i test esportati controllano solo che i campi documentati esistano, non che la risposta sia identica. Per una documentazione completa, copia la risposta reale nell'esempio.

6. Provoca un errore

1. Cambia il codice in 0100100, con 7 cifre, ed esegui. L'app mostra Falha na requisição (richiesta fallita): “Failed to fetch”.
2. Cambialo in 99999999 ed esegui. Torna 200 OK con {"erro": "true"}.

Il primo caso sembra un'API fuori servizio, ma non lo è. La sezione Provare le richieste e CORS spiega che cosa è successo. Nel secondo, la documentazione di ViaCEP mostra "erro": true, booleano, e la risposta reale conteneva "true", testo. ^[12] Questo tipo di discrepanza è proprio ciò che provare la documentazione rivela.

7. Salva ed esporta

1. Fai clic su Salvar (salva, Ctrl+S) e registra il file, per esempio, come viacep.html. Quel file è già la documentazione pronta da inviare.
2. In Exportar ▾ → OpenAPI 3 (esporta), l'app scarica viacep-openapi.json. Nella prova di questo tutorial, il file ha superato la validazione del pacchetto @apidevtools/swagger-parser, che confronta il documento con lo schema ufficiale di OpenAPI 3.0.
3. In Exportar ▾ → Testes Python (test Python), l'app scarica test_viacep.py. Eseguito con pytest, il test è passato contro il ViaCEP reale.

L'interfaccia

Barra superiore

Titolo e versione dell'API, l'avviso ● não salvo (non salvato), l'interruttore Visualizar / Editar (vedi / modifica) e i pulsanti Salvar, Exportar ▾, Importar ▾ e Novo.

Barra laterale

Il campo Filtrar endpoints…, che cerca nel metodo, nel percorso, nel riepilogo e nella tag; gli endpoint raggruppati per tag; e gli schema. In modalità modifica aggiunge Informações gerais, Autenticação, Tags, + Endpoint e + Schema.

Area centrale

In modalità vedi, la documentazione navigabile con un pannello di prova in ogni endpoint. In modalità modifica, il modulo dell'elemento scelto nella barra laterale.

Avvisi

Brevi messaggi compaiono per qualche secondo in fondo allo schermo: file salvato, parametri rilevati, errore di importazione.

Sugli schermi più stretti di 860 px, la barra laterale scompare e si naviga solo scorrendo l'area centrale.

Nomi dei pulsanti

La modalità Editar nel dettaglio

Parametri

Ogni riga ha nome, posizione (path, query, header, cookie), tipo, il segno di obbligatorio, descrizione ed esempio. Un parametro di percorso è sempre obbligatorio: la specifica OpenAPI lo esige, e l'app applica la regola all'esportazione anche se il segno è spento. ^[8] I tipi integer, number e boolean fanno esportare l'esempio come numero o booleano, e non come testo.

Corpo e risposte

Il campo Content-Type suggerisce i tipi più comuni. I campi di esempio JSON vengono validati mentre scrivi e hanno il pulsante Formatar JSON. Un esempio che non è JSON viene accettato, ma trattato come testo.

Gli endpoint segnati come deprecati appaiono barrati, con il badge “obsoleto”. È il modo standard per avvisare che qualcosa sparirà, senza rimuoverlo all'improvviso.

Provare le richieste e CORS

Il pannello Testar requisição compone l'URL con il server scelto, riempie i parametri con gli esempi, aggiunge la credenziale digitata e invia la richiesta dal browser stesso. Il risultato mostra il codice, il tempo, le intestazioni della risposta, il comando curl equivalente e il corpo formattato.

Perché il browser blocca alcune chiamate

Per sicurezza, il browser lascia che uno script legga la risposta di un altro sito solo se quel sito lo autorizza, con l'intestazione Access-Control-Allow-Origin. Questo meccanismo si chiama CORS (Cross-Origin Resource Sharing). ^[11] Senza autorizzazione, il browser consegna allo script solo un errore generico, e l'app mostra “Failed to fetch”.

È ciò che è successo con il codice di 7 cifre. Chiamato fuori dal browser, ViaCEP ha risposto 400 Bad Request con una pagina HTML e senza l'intestazione CORS; la ricerca valida è tornata con Access-Control-Allow-Origin: *. L'errore c'era, ma il browser l'ha nascosto.

Inoltre, le richieste con Authorization, con Content-Type: application/json o con metodi come PUT e DELETE sono precedute da una richiesta OPTIONS, la preflight, che anche il server deve approvare. ^[11] Molte API aziendali non aprono CORS a qualsiasi origine.

Che cosa fare quando la prova fallisce

1. Apri Comando curl, fai clic su Copiar curl (copia curl) ed eseguilo nel terminale. curl non è un browser e non applica CORS: vedi il codice e il corpo veri.
2. Se curl funziona, l'API è attiva e il blocco è del browser. Documenta normalmente; è solo la prova nell'app che non è possibile.
3. Se anche curl fallisce, controlla server, percorso, credenziale e rete.

Salvare

L'app non usa né server né database. La documentazione sta in un blocco JSON dentro l'HTML stesso, e salvare significa scrivere un nuovo HTML con quel blocco aggiornato.

Che cosa non viene scritto: le credenziali digitate per le prove, i valori cambiati nel pannello di prova e i risultati delle chiamate. Se provi a chiudere la scheda con modifiche in sospeso, il browser chiede conferma.

Importare

Molte API hanno già una specifica, generata dal framework stesso del server. Importare evita di riscrivere tutto.

Se il documento attuale ha già degli endpoint, l'app chiede che cosa fare:

• Mesclar (unisci) aggiunge endpoint, tag, server e schema che ancora non esistono. Un endpoint con lo stesso metodo e percorso di uno esistente viene ignorato. Nella prova, unire ViaCEP all'esempio delle Correios ha dato 5 endpoint.
• Substituir tudo (sostituisci tutto) scarta la documentazione attuale.

Quando la specifica d'origine non ha un esempio, l'app ne crea uno dallo schema, con valori generici come "string" e 0. Rivedi questi esempi dopo l'importazione.

Esportare

I test in Python

Il file generato inizia con le istruzioni di installazione ed esecuzione (in portoghese). Ogni test chiama un endpoint con i valori di esempio, controlla il codice di successo documentato e verifica che i campi dell'esempio di risposta esistano nella risposta reale con lo stesso tipo JSON.

pip install pytest requests
pytest -v test_viacep.py

• L'URL base e le credenziali vengono da variabili d'ambiente: API_BASE_URL, API_TOKEN, API_USER e API_PASS, oppure API_KEY. Così nessuna password resta nel codice.
• I metodi che modificano dati (POST, PUT, PATCH, DELETE) vengono eseguiti solo con API_ALLOW_WRITE=1. Senza, risultano saltati.
• Se l'API ha autenticazione e l'endpoint documenta la risposta 401, l'app crea anche un test senza credenziali che si aspetta 401.
• API_MAX_MS imposta un tempo massimo di risposta, se vuoi tenere d'occhio la lentezza.

Prompt di IA

Un'IA accelera le parti lente della documentazione: trovare gli endpoint sparsi nel codice, trasformare chiamate sciolte in una specifica, scrivere descrizioni ed estendere i test. Sbaglia anche con sicurezza: inventa campi, tira a indovinare i codici di stato e descrive comportamenti che l'API non ha. Tratta il risultato come una bozza e controlla ogni endpoint con il pannello Testar requisição (prova richiesta), che parla con l'API reale. Per scrivere prompt migliori, vedi il tutorial sui prompt.

Prima di incollare: togli token, password, chiavi di API, indirizzi interni e dati dei clienti da ciò che va all'IA. Sostituiscili con valori inventati e segui la politica della tua organizzazione. L'app parla solo con l'API che stai provando, ma il servizio di IA riceve tutto ciò che vi incolli.

Sostituisci le parti tra parentesi quadre e incolla nello strumento di IA che usi. I prompt seguono l'ordine del lavoro: quelli da 1 a 4 producono la documentazione, quelli da 5 a 9 la rivedono e la mettono in uso. Ognuno funziona da solo. I nomi dei campi dell'app restano in portoghese, come sullo schermo.

1. Intervistare prima di documentare

Quando l'API vive ancora nella testa di chi l'ha costruita. L'IA chiede invece di supporre.

Sei un redattore tecnico esperto di API REST e della specifica OpenAPI.
Voglio documentare questa API: [descrivi in poche frasi che cosa fa e chi la usa].

Prima di scrivere qualsiasi documentazione, intervistami:
- Fai una domanda alla volta e aspetta la mia risposta.
- Copri: l'URL base di ogni ambiente; il metodo di autenticazione; ogni risorsa e le operazioni su di essa (metodo e percorso); i parametri di percorso, di query e di intestazione, con tipo, obbligatorietà e un esempio; i corpi delle richieste; le risposte di successo e di errore, con il codice e un esempio di corpo; la paginazione; i limiti d'uso; ciò che è deprecato.
- Chiedi soprattutto degli errori: che cosa succede con dati non validi, senza credenziale, senza permesso e con una risorsa inesistente.
- Non inventare risposte. Se non lo so, registralo come punto aperto.

Alla fine, consegna: una tabella degli endpoint (metodo, percorso, riepilogo, tag), i parametri e le risposte di ognuno, esempi di corpo in JSON e l'elenco dei punti aperti.

2. Trovare gli endpoint nel codice

Per API già programmate ma senza documentazione. Chiede l'origine di ogni elemento, il che facilita il controllo.

A partire dal codice qui sotto, ricostruisci il contratto dell'API REST che implementa.

Linguaggio e framework: [per esempio: Java con Spring, C# con ASP.NET, Node con Express, Python con FastAPI, ObjectScript con %CSP.REST]
Codice:
[incolla i controller, le rotte o l'UrlMap, e le classi di input e output]

Consegna:
1. Tabella degli endpoint: metodo, percorso (con {parametri}), riepilogo, tag suggerita e il file e la riga da cui proviene.
2. Per ogni endpoint: parametri (nome, posizione path, query, header o cookie, tipo, obbligatorio), il corpo della richiesta con un esempio in JSON, e le risposte con codice ed esempio di corpo.
3. I codici di errore che il codice restituisce davvero, e in quale situazione.
4. Come viene verificata l'autenticazione.
5. Lacune: ritorni che dipendono da codice non presente qui, eccezioni non gestite e comportamenti ambigui, con una domanda per ciascuno.

Non dedurre ciò che il codice non mostra. Usa esempi inventati.

3. Generare l'OpenAPI da importare nell'app

Trasforma ciò che hai raccolto in un file che l'app importa in un colpo solo, invece di scrivere endpoint per endpoint. Il formato richiesto è quello che usa l'importatore dell'app.

Genera una specifica OpenAPI 3.0.3 in JSON per l'API descritta alla fine. Sarà importata in API Docs, un editor che legge un sottoinsieme di OpenAPI.

Rispondi solo con il JSON, senza commenti e senza blocchi di codice.

Usa solo questi elementi:
- "openapi": "3.0.3" e "info" con "title", "version" e "description". La descrizione accetta Markdown semplice: **grassetto**, `codice`, link ed elenchi con "- ".
- "servers": un elenco con "url" (senza barra finale) e "description".
- "tags": un elenco con "name" e "description". Ogni operazione usa una sola tag.
- "paths": un'operazione per metodo (get, post, put, patch, delete), con "tags", "summary" (breve, che inizia con un verbo), "description" e, se serve, "deprecated": true.
- "parameters": "name", "in" (path, query, header o cookie), "required", "description", "schema" con "type" (string, integer, number, boolean, array o object) ed "example". Ogni {parametro} del percorso ha bisogno di un parametro con "in": "path" e "required": true.
- "requestBody" solo in post, put e patch: "description" e "content" con un solo tipo di media, di solito "application/json", che contiene "example".
- "responses": per ogni codice, "description" e, quando c'è un corpo, "content": {"application/json": {"example": ...}}. Includi le risposte di errore che l'API usa davvero, con il corpo dell'errore.
- "components.securitySchemes" con un solo schema: {"type": "http", "scheme": "bearer"}, {"type": "http", "scheme": "basic"} oppure {"type": "apiKey", "name": "...", "in": "header"}; e "security" alla radice che vi punta. Se l'API è pubblica, ometti entrambi.
- "components.schemas" con gli oggetti principali.

Regole:
- Non inventare endpoint, campi né codici. Ciò che manca va in "info.description", in un elenco chiamato Punti aperti.
- Esempi realistici e inventati: mai token, password, documenti o indirizzi e-mail reali.
- Gli esempi di risposta usano gli stessi nomi di campo degli schema.

Informazioni sull'API:
[incolla il risultato del prompt 1, 2 o 4, la documentazione esistente o la tua descrizione]

4. Trasformare chiamate reali in documentazione

Quando hai solo chiamate che funzionano. Nel browser, apri gli strumenti per sviluppatori, scheda Rete, fai clic destro sulla richiesta e usa “Copia come cURL”.

Qui sotto ci sono chiamate reali a un'API, in cURL, con le risposte ricevute.
Ho già sostituito token e dati personali con valori inventati.

[incolla ogni cURL seguito dal codice di stato e dal corpo della risposta]

Fai così:
1. Raggruppa le chiamate per risorsa e deduci gli endpoint: metodo e percorso, sostituendo i valori che cambiano con {parametri} dal nome chiaro (per esempio /ordini/123 diventa /ordini/{id}).
2. Per ogni endpoint, elenca i parametri di percorso, di query e di intestazione, con tipo e un esempio preso dalle chiamate.
3. Usa i corpi reali come esempi di richiesta e di risposta, accorciando gli elenchi lunghi a due elementi.
4. Individua l'autenticazione dalle intestazioni (Authorization, X-API-Key o altra), senza ripeterne il valore.
5. Segna come “visto una volta” ciò che compare in una sola chiamata, ed elenca ciò che resta da sapere: risposte di errore non osservate, parametri facoltativi e limiti.

Consegna in tabelle, pronte da usare nel prompt 3.

5. Rivedere la documentazione

Una seconda lettura prima di pubblicare. Usa il file di Exportar ▾ → Markdown oppure OpenAPI 3.

Rivedi la documentazione dell'API qui sotto come chi deve integrarsi con essa per la prima volta.

[incolla il Markdown o l'OpenAPI esportato da API Docs]

Controlla e segnala, endpoint per endpoint:
- Un metodo coerente con l'azione: GET legge soltanto, POST crea, PUT sostituisce, PATCH modifica una parte, DELETE rimuove.
- Percorsi fatti di sostantivi e con uno schema di nomi coerente (plurale o singolare, maiuscole, trattini).
- Parametri senza descrizione, senza esempio, con il tipo sbagliato, o parametri di percorso che non compaiono nel percorso.
- Risposte di errore mancanti (400, 401, 403, 404, 422, 500) ed errori restituiti con codice 200.
- Esempi che non corrispondono allo schema o tra loro.
- Dati negli esempi che sembrano reali o sensibili: token, password, documenti, indirizzi e-mail.
- Riepiloghi vaghi e descrizioni che non dicono l'effetto dell'operazione.

Consegna una tabella con: endpoint, problema, gravità (alta, media, bassa) e la correzione suggerita, come testo pronto da incollare nell'app. Concludi con le tre correzioni più importanti.

6. Scrivere testi per chi integra

Migliora riepiloghi e descrizioni senza cambiare il contratto. Il risultato ha la forma dei campi dell'app.

Riscrivi i testi di questa documentazione di API per chi dovrà integrarsi con essa.

[incolla il Markdown esportato o l'elenco degli endpoint con riepilogo e descrizione]
Lingua dei testi: [per esempio: portoghese, italiano]

Per ogni endpoint, consegna:
- Riepilogo: fino a 60 caratteri, che inizia con un verbo (per esempio, Cerca un codice postale).
- Descrizione: fino a 4 frasi. Che cosa fa l'operazione, quando usarla, effetti collaterali e un'avvertenza importante. Usa solo questo Markdown: **grassetto**, `codice`, link ed elenchi con "- ".
- Descrizione di ogni parametro: una frase con il formato atteso e un esempio.

Scrivi anche la descrizione generale dell'API, con: a che cosa serve, come autenticarsi, dove ottenere la credenziale e un primo passo.

Non cambiare metodi, percorsi, nomi dei campi né codici. Se un testo attuale è sbagliato rispetto al contratto, segnalalo a parte.

7. Estendere i test in Python

Il file di Exportar ▾ → Testes Python copre il percorso felice. Questo prompt aggiunge i casi di errore e di bordo.

Qui sotto c'è un file di test pytest generato dalla documentazione di un'API, e la documentazione.

Test:
[incolla il test_*.py esportato]
Documentazione:
[incolla l'OpenAPI o il Markdown esportato]

Aggiungi test, senza cambiare quelli esistenti:
- Per ogni endpoint: parametro obbligatorio mancante, tipo sbagliato, valore fuori limite e risorsa inesistente, aspettandoti i codici definiti dalla documentazione.
- Per gli endpoint con autenticazione: senza credenziale (401) e, se la documentazione lo definisce, senza permesso (403).
- Per gli elenchi paginati: prima pagina, pagina vuota e dimensione massima.

Regole:
- Riusa la fixture api e le funzioni url, check_status, json_of e assert_shape del file.
- Leggi URL e credenziali dalle variabili d'ambiente già usate; non scrivere mai segreti nel codice.
- Segna con @WRITE ogni test che usa POST, PUT, PATCH o DELETE.
- Se la documentazione non dice quale codice aspettarsi, non inventarlo: crea il test con pytest.skip e il motivo.

Consegna solo il codice nuovo, pronto da incollare alla fine della classe corrispondente, e un elenco di ciò che resta senza test.

8. Diagnosticare una chiamata fallita

Per quando il pannello di prova mostra un errore e non sai se il problema è l'API, la rete, il browser o la documentazione.

Una chiamata a un'API è fallita. Aiutami a trovarne la causa.

Messaggio nel browser: [per esempio: Failed to fetch, oppure il codice e il corpo mostrati]
Comando curl (senza il token): [incolla il curl copiato dal pannello Testar requisição]
Risultato del curl nel terminale: [codice di stato, intestazioni e corpo, oppure il messaggio di errore]
Che cosa dice la documentazione che dovrebbe succedere: [codice e corpo attesi]

Classifica la causa più probabile tra: blocco CORS nel browser, rete o DNS, certificato HTTPS, credenziale mancante o scaduta, mancanza di permesso, richiesta malformata, risorsa inesistente, errore del server, oppure documentazione non aggiornata.

Spiega su quali prove ti sei basato, indica il prossimo test che conferma l'ipotesi e, se serve, che cosa correggere nella documentazione. Non supporre nulla che le prove non mostrino.

9. Implementare la classe generata per InterSystems IRIS

L'esportazione InterSystems IRIS crea rotte e metodi che restituiscono la risposta di esempio, con segni TODO. Questo prompt chiede l'implementazione mantenendo il contratto.

Qui sotto c'è una classe ObjectScript che estende %CSP.REST, generata dalla documentazione di un'API. Ogni metodo restituisce la risposta di esempio e ha un commento TODO.

Classe:
[incolla il .cls esportato]
Regole di business e dati:
[descrivi le tabelle o le classi persistenti coinvolte e che cosa deve fare ogni endpoint]

Implementa i metodi segnati con TODO:
- Non cambiare l'UrlMap, i nomi dei metodi né i codici e i campi documentati.
- Usa %DynamicObject e %DynamicArray per costruire il JSON di risposta.
- In SQL, usa parametri (? o :variabile); non concatenare mai testo dell'utente nella query.
- Rispondi con ..Erro(codice, messaggio) negli errori documentati: 400 per input non valido e 404 per risorsa inesistente.
- Mantieni il blocco Try/Catch esistente.

Consegna la classe completa e poi l'elenco delle ipotesi che hai fatto sui dati.

Come importare il JSON del prompt 3

1. Copia la risposta dell'IA in un editor di testo e salvala con l'estensione .json, per esempio mia-api.json.
2. Nell'app, usa Importar ▾ → Swagger / OpenAPI, oppure trascina il file sulla finestra. Se ci sono già endpoint, scegli Mesclar (unisci) o Substituir tudo (sostituisci tutto).
3. Passa per la modalità Editar (modifica): controlla percorsi, parametri ed esempi, e leggi i punti aperti nella descrizione generale.
4. In modalità Visualizar (vedi), prova ogni endpoint con Testar requisição. Dove la risposta reale differisce dall'esempio, vale la risposta reale.
5. Fai clic su Salvar (salva).

Per API grandi, chiedi un JSON per tag e importali uno per uno con Mesclar: l'app aggiunge ciò che è nuovo e ignora gli endpoint con lo stesso metodo e percorso.

Errori comuni

• “Failed to fetch: l'API è giù”

  Quasi sempre è CORS o la rete. Esegui curl prima di concludere qualsiasi cosa.

• Credenziali nell'esempio o nella descrizione

  Il file HTML è fatto per essere inviato. Token e password vanno solo nei campi del pannello di prova, che non vengono salvati.

• Esempi inventati

  Un esempio scritto a memoria si allontana dall'API reale. Esegui la chiamata e usa la risposta vera come esempio.

• Documentare solo il successo

  Chi integra deve sapere che cosa torna quando qualcosa va storto. Documenta 400, 401, 404 e il corpo dell'errore.

• Corpo in un GET

  Un contenuto in un GET non ha significato definito in HTTP. Per i filtri, usa i parametri di query.

• Dimenticare di salvare

  Finché compare “● não salvo”, nulla è stato scritto. Usa Ctrl+S.

Limiti e soluzione dei problemi

L'app copre l'essenziale di OpenAPI, non l'intera specifica. Che cosa resta fuori:

• Un solo metodo di autenticazione per tutta l'API. Non c'è autenticazione per endpoint, né OAuth 2 con i flussi, né più di uno schema. All'importazione si usa solo il primo schema, e OAuth 2 diventa Bearer.
• I parametri hanno solo il tipo, senza formato, elenco di valori, minimo o massimo.
• Gli esempi di risposta sono sempre esportati come application/json, e le intestazioni di risposta non sono documentate.
• Gli schema stanno in un elenco a sé; gli endpoint non vi puntano con $ref.
• All'importazione si perdono i parametri formData di Swagger 2.0 e le intestazioni di risposta; di più tag o più esempi, si tiene il primo.
• Lo YAML è letto da un interprete proprio dell'app, che copre l'uso comune. Se un file YAML fallisce, convertilo in JSON e importalo di nuovo.

Ripasso veloce

Prova a rispondere prima di aprire ogni domanda.

Riferimenti

1. Giovani Perotto Mesquita, “API Docs”, applicazione in un unico file HTML (interfaccia in portoghese), giovanipm.github.io/api-docs.html.
2. Roy Thomas Fielding (in inglese), “Architectural Styles and the Design of Network-based Software Architectures”, tesi di dottorato, Università della California a Irvine, 2000, capitolo 5, consultato l'11 novembre 2026, ics.uci.edu/~fielding/pubs/dissertation/top.htm.
3. IETF (in inglese), RFC 9110, “HTTP Semantics”, giugno 2022, sezioni 9 (metodi) e 15 (codici di stato), consultato l'11 novembre 2026, rfc-editor.org/rfc/rfc9110.
4. IETF (in inglese), RFC 3986, “Uniform Resource Identifier (URI): Generic Syntax”, 2005, consultato l'11 novembre 2026, rfc-editor.org/rfc/rfc3986.
5. IETF (in inglese), RFC 8259, “The JavaScript Object Notation (JSON) Data Interchange Format”, 2017, consultato l'11 novembre 2026, rfc-editor.org/rfc/rfc8259.
6. IETF (in inglese), RFC 7617, “The 'Basic' HTTP Authentication Scheme”, 2015, consultato l'11 novembre 2026, rfc-editor.org/rfc/rfc7617.
7. IETF (in inglese), RFC 6750, “The OAuth 2.0 Authorization Framework: Bearer Token Usage”, 2012, consultato l'11 novembre 2026, rfc-editor.org/rfc/rfc6750.
8. OpenAPI Initiative (in inglese), “OpenAPI Specification v3.0.3”, 20 febbraio 2020, compresa l'appendice A, “Revision History”, consultato l'11 novembre 2026, spec.openapis.org/oas/v3.0.3.html.
9. OpenAPI Initiative (in inglese), “OpenAPI Specification v3.2.0”, settembre 2025, consultato l'11 novembre 2026, spec.openapis.org/oas/v3.2.
10. Wikipedia (in inglese), “OpenAPI Specification”, consultato l'11 novembre 2026, en.wikipedia.org/wiki/OpenAPI_Specification. Divergenza: Wikipedia data la creazione di Swagger al 2010 e l'annuncio della OpenAPI Initiative al novembre 2015; la cronologia delle revisioni della specifica [8] registra la versione 1.0 il 10 agosto 2011 e la donazione il 31 dicembre 2015.
11. MDN Web Docs (in inglese), “Cross-Origin Resource Sharing (CORS)”, consultato l'11 novembre 2026, developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS.
12. ViaCEP (in portoghese), pagina del webservice, consultato l'11 novembre 2026, viacep.com.br. Divergenza: la pagina mostra "erro": true per un codice inesistente; la chiamata reale di questo tutorial, l'11 novembre 2026, ha restituito "erro": "true".
13. Postman (in inglese), “Postman Collection Format v2.1.0”, schema JSON, consultato l'11 novembre 2026, schema.getpostman.com/json/collection/v2.1.0/collection.json.
14. pytest (in inglese), documentazione, consultato l'11 novembre 2026, docs.pytest.org.
15. Requests (in inglese), “Requests: HTTP for Humans”, documentazione, consultato l'11 novembre 2026, requests.readthedocs.io.
16. InterSystems (in inglese), “Creating REST Services”, documentazione di InterSystems IRIS, consultato l'11 novembre 2026, docs.intersystems.com/irislatest/csp/docbook/Doc.View.cls?KEY=GREST.
17. MDN Web Docs (in inglese), “File System API”, consultato l'11 novembre 2026, developer.mozilla.org/en-US/docs/Web/API/File_System_API.
18. IETF (in inglese), RFC 5789, “PATCH Method for HTTP”, 2010, consultato l'11 novembre 2026, rfc-editor.org/rfc/rfc5789.

Qué es API Docs

API Docs es un editor y visor de documentación de API REST en un único archivo HTML. ^[1] Muestra los endpoints de una API, permite probarlos en el navegador y exporta la documentación a OpenAPI, Postman, pruebas en Python, InterSystems IRIS, Markdown y PDF. Los datos se guardan dentro del propio archivo: para compartir la documentación, basta con enviar el HTML.

Abrir API Docs →

Este tutorial tiene dos mitades. La primera explica la teoría detrás de cada campo de la pantalla: qué es una API, cómo es una petición HTTP, qué significan los códigos de estado, cómo funciona la autenticación y por qué existe el estándar OpenAPI. La segunda es un recorrido práctico: vas a documentar y probar una API pública real, ViaCEP, un servicio brasileño de consulta de códigos postales (CEP), y exportar el resultado. Al final, prompts de IA listos para copiar aceleran cada etapa.

Qué necesitas

• Un navegador actual. Chrome y Edge escriben directamente en el archivo; en los demás, guardar descarga una copia.
• Conexión a internet solo para probar peticiones e importar por URL. Ver, editar, importar un archivo y exportar funcionan sin red.
• Ningún conocimiento previo de programación. Quien ya programa aprovechará más las secciones de exportación.

Qué es una API

API significa Application Programming Interface, interfaz de programación de aplicaciones. Es un contrato entre dos programas: uno, el servidor, ofrece funciones; el otro, el cliente, las pide siguiendo reglas acordadas. Una app de entregas que rellena la dirección a partir del código postal no tiene la base de códigos del país: se lo pregunta a una API y recibe la respuesta lista.

El contrato dice qué se puede pedir, cómo pedirlo y qué vuelve. No dice cómo el servidor hace el trabajo por dentro. Eso es lo que permite cambiar la base de datos o el lenguaje del servidor sin romper a los clientes, siempre que el contrato siga igual. Documentar una API es escribir ese contrato de forma que personas y programas puedan leerlo.

REST

La mayoría de las API de la web sigue, en mayor o menor grado, el estilo REST (Representational State Transfer), descrito por Roy Fielding en su tesis doctoral de 2000. ^[2] Fielding define REST como un conjunto de restricciones de arquitectura. Las que más aparecen en el día a día son:

• Cliente y servidor separados. Cada lado evoluciona sin depender del otro.
• Sin estado (stateless). Cada petición lleva todo lo que el servidor necesita para atenderla, incluida la credencial. El servidor no “recuerda” la conversación anterior.
• Caché. La respuesta indica si puede reutilizarse, lo que ahorra viajes al servidor.
• Interfaz uniforme. Todo es un recurso identificado por una dirección (la dirección de un código postal, la lista de pedidos de un cliente), y las operaciones sobre él usan los mismos pocos verbos de HTTP.

En la práctica, “API REST” suele significar una API que usa HTTP, organiza las direcciones por recursos e intercambia datos en JSON. API Docs documenta justamente ese tipo de API.

Anatomía de una petición

Cliente y servidor conversan por HTTP. Cada conversación es un par: el cliente envía una petición y el servidor devuelve una respuesta. El significado de cada parte lo define la RFC 9110, la norma actual de la semántica de HTTP. ^[3]

La URL: servidor, ruta y parámetros

La dirección de un recurso es una URL, cuya sintaxis define la RFC 3986. ^[4] En API Docs, la URL se arma a partir de tres campos que rellenas por separado:

Servidor (URL base)

El comienzo común a todas las direcciones, como https://api.correios.com.br. Una API puede tener varios: producción, pruebas, local.

Ruta

El recurso dentro del servidor, como /cep/v2/enderecos/{cep}. Las llaves marcan una parte variable.

Parámetro de ruta (path)

El valor que ocupa el lugar de las llaves. Identifica qué recurso: 01001001. Siempre es obligatorio.

Parámetro de consulta (query)

Pares nombre=valor después del ?, separados por &. Filtran, ordenan o paginan: ?uf=SP&size=50. Suelen ser opcionales.

Cabecera (header)

Información sobre la petición fuera de la URL: formato aceptado (Accept), credencial (Authorization), idioma.

Cookie

Un valor que el navegador guarda y reenvía al mismo servidor. Raro en API que usan otros sistemas.

Esos cuatro lugares son exactamente las opciones de la columna Local (ubicación) de los parámetros en la app: path, query, header y cookie.

Los métodos

El método dice qué hacer con el recurso. La RFC 9110 clasifica los métodos por dos propiedades que afectan a la seguridad y a los reintentos: un método seguro es, por definición, de solo lectura; uno idempotente es aquel en que repetir la misma petición tiene el mismo efecto que hacerla una vez. ^[3]

Por qué importa: si la red se cae en medio de un PUT, el cliente puede repetirlo sin miedo; repetir un POST puede crear dos pedidos. Por eso las pruebas que exporta la app no ejecutan métodos que cambian datos, salvo que lo autorices.

El cuerpo y el JSON

Las peticiones POST, PUT y PATCH llevan datos en el cuerpo. La cabecera Content-Type indica el formato; en API REST casi siempre es application/json. JSON es un formato de texto con objetos entre llaves, listas entre corchetes, textos entre comillas, números y los valores true, false y null, definido por la RFC 8259. ^[5]

{
  "numero": "9912345678",
  "dr": 10
}

Una petición GET no debe llevar cuerpo: la RFC 9110 dice que el contenido en un GET no tiene significado definido. ^[3] Por eso la app no muestra el campo de cuerpo para GET y HEAD.

Respuestas y códigos de estado

Toda respuesta empieza con un código de tres dígitos. El primer dígito indica la clase, y es lo que la app usa para colorear las insignias de las respuestas. ^[3]

La distinción entre 4xx y 5xx dice de quién es la culpa y, por tanto, quién debe actuar. Una buena documentación también enumera las respuestas de error, con un ejemplo del cuerpo, porque es ahí donde quien desarrolla el cliente más necesita ayuda.

Autenticación

La mayoría de las API necesita saber quién pide. Como REST no tiene estado, la credencial va en cada petición, normalmente en la cabecera Authorization. La app ofrece los cuatro esquemas más comunes en Editar → Autenticação (Editar → Autenticación):

En la app, la autenticación vale para todos los endpoints. Al probar, los campos de credencial aparecen en el panel Testar requisição (probar petición). Quedan solo en memoria y no se escriben en el archivo al guardar.

Documentar con OpenAPI

Una documentación en texto libre sirve para personas, pero no para programas. La Especificación OpenAPI lo resuelve: define una descripción estándar e independiente del lenguaje para API HTTP, que personas y computadoras pueden leer sin acceso al código fuente. ^[8] Un documento OpenAPI es un objeto JSON, que puede escribirse en JSON o en YAML. ^[8]

Un poco de historia

El formato nació como Swagger, en la empresa Wordnik. Wikipedia sitúa su creación en 2010; el historial de revisiones de la propia especificación registra la versión 1.0 el 10 de agosto de 2011 y Swagger 2.0 el 8 de septiembre de 2014. ^{[10] [8]} En 2015 la especificación se donó a la OpenAPI Initiative, bajo la Linux Foundation, y pasó a llamarse OpenAPI. La fecha de la donación difiere entre las fuentes: Wikipedia cita el anuncio de la iniciativa en noviembre de 2015, y el historial de la especificación registra la donación el 31 de diciembre de 2015. La versión 3.0.0 salió el 26 de julio de 2017, y la 3.0.3, la que exporta la app, el 20 de febrero de 2020. ^[8] Ya existen versiones más nuevas: la 3.2.0 se publicó en septiembre de 2025. ^[9] El nombre Swagger sigue vivo en las herramientas de SmartBear, como Swagger UI, y por eso se sigue diciendo “el Swagger de la API”.

Por qué ayuda un estándar

• Una fuente, muchos usos. Del mismo archivo salen la página de documentación, colecciones para herramientas de prueba, clientes en varios lenguajes y esqueletos de servidor.
• Contrato antes que código. En el estilo design-first, el equipo escribe y discute la especificación antes de programar, y cliente y servidor pueden desarrollarse en paralelo. En el estilo code-first, la especificación se genera a partir del código ya hecho. API Docs sirve al primer estilo y también importa el resultado del segundo.
• Verificable. Un documento OpenAPI puede validarse con un programa, y las pruebas pueden comprobar que la API real cumple lo escrito.

Adónde va cada campo de la app

Cada campo de la app corresponde a una parte del documento OpenAPI exportado. Conocer esa relación ayuda a leer cualquier archivo OpenAPI que encuentres.

Los schemas describen la forma de un objeto: qué campos tiene y de qué tipo. OpenAPI 3.0 usa para ello un subconjunto extendido de JSON Schema. ^[8]

Primeros pasos con el ejemplo

El archivo trae una documentación de ejemplo, “API Busca CEP — Correios”, una API de consulta de códigos postales del servicio postal brasileño. Muestra cómo se ve una API completa en la app: autenticación por token, un endpoint que genera el token, una consulta, una búsqueda paginada y un schema. La propia descripción del ejemplo advierte que rutas y campos deben comprobarse en el portal oficial de Correios antes de cualquier uso real. ^[1] En cinco minutos:

1. Abre API Docs. Empieza en el modo Visualizar (ver), en la vista general: título, versión, descripción, servidor y tipo de autenticación.
2. En la barra lateral, haz clic en GET /cep/v2/enderecos/{cep}. La tarjeta del endpoint se abre con la descripción, la tabla de parámetros y las respuestas. El asterisco rojo junto a cep marca un parámetro obligatorio.
3. Fíjate en los colores: GET azul, POST verde; respuestas 2xx en verde, 4xx en naranja y 5xx en rojo.
4. En el campo Filtrar endpoints…, escribe token. Solo queda el endpoint de autenticación. Borra el filtro.
5. Al final de la barra lateral, en Schemas, haz clic en Endereco (dirección). La definición del objeto aparece en JSON.

Al final de cada tarjeta abierta está el panel Testar requisição. No lo uses con el ejemplo de Correios: esa API exige contrato y token. La prueba de verdad llega en la siguiente sección, con una API abierta.

Tu primer documento: ViaCEP

ViaCEP es un servicio brasileño gratuito de consulta de códigos postales que no exige registro. Una consulta es un GET a viacep.com.br/ws/{cep}/json/, con el código de 8 dígitos. ^[12] El recorrido de abajo se ejecutó con clics reales en la app el 11 de noviembre de 2026. Los textos escritos en la app quedan en portugués, como en las capturas; el significado en español va entre corchetes.

1. Empieza un documento en blanco

1. Si quieres conservar el ejemplo, guarda antes una copia del archivo.
2. Haz clic en Novo (nuevo) y confirma. La app pasa al modo Editar, en la página Informações gerais (información general).

2. Rellena la información general

1. Título: ViaCEP. Versão (versión): 1.0. La versión es la de tu documentación; cuando el contrato cambie, súbela.
2. Descrição (descripción): un párrafo sobre la API. El campo acepta Markdown sencillo: **negrita**, `código`, enlaces y listas con “- ”.
3. En Servidores, cambia la URL base a https://viacep.com.br, sin barra final, y la descripción a Produção (producción).

La autenticación queda en Nenhuma (ninguna), que ya es el valor por defecto de un documento nuevo.

3. Crea el endpoint

1. En la barra lateral, haz clic en + Endpoint. Aparece un GET /novo-recurso.
2. Caminho (ruta): /ws/{cep}/json/. Resumo (resumen): Consultar um CEP [consultar un código postal]. Tag: CEP. La tag agrupa endpoints en la barra lateral.
3. Haz clic en Detectar {parâmetros} do caminho (detectar parámetros de la ruta). La app lee las llaves de la ruta y crea el parámetro cep, ubicación path, obligatorio.
4. En la fila del parámetro, escribe la descripción CEP com 8 dígitos, sem hífen [código de 8 dígitos, sin guion] y el ejemplo 01001000. El ejemplo es el valor con el que empieza el panel de prueba.

4. Documenta las respuestas

1. En la respuesta 200 que ya existe, escribe la descripción: Endereço encontrado. CEP inexistente também volta 200, com o campo `erro`. [Dirección encontrada. Un código inexistente también devuelve 200, con el campo erro.]
2. En Exemplo de resposta (ejemplo de respuesta), pega un JSON corto y haz clic en Formatar JSON (formatear JSON):

   {"cep":"01001-000","logradouro":"Praça da Sé","complemento":"lado ímpar","bairro":"Sé","localidade":"São Paulo","uf":"SP","ddd":"11"}

   Si el JSON está mal, el cuadro se pone rojo con el aviso “JSON inválido”.
3. Haz clic en + Resposta (añadir respuesta), escribe el código 400 y la descripción Formato inválido (não tem 8 dígitos). [Formato no válido (no tiene 8 dígitos).]

5. Prueba de verdad

1. Haz clic en Visualizar (ver) y, en la barra lateral, en GET /ws/{cep}/json/.
2. En el panel Testar requisição, el campo cep ya trae 01001000, y la URL completa aparece junto al botón.
3. Haz clic en Executar (ejecutar). En la prueba de este tutorial, 200 OK llegó en menos de un segundo con la dirección de la Praça da Sé.

Compara la respuesta real con el ejemplo que escribiste: tiene campos de más. Es habitual, y por eso las pruebas exportadas solo comprueban que los campos documentados existan, no que la respuesta sea idéntica. Para una documentación completa, copia la respuesta real en el ejemplo.

6. Provoca un error

1. Cambia el código a 0100100, con 7 dígitos, y ejecuta. La app muestra Falha na requisição (fallo en la petición): “Failed to fetch”.
2. Cámbialo a 99999999 y ejecuta. Vuelve 200 OK con {"erro": "true"}.

El primer caso parece una caída de la API, pero no lo es. La sección Probar peticiones y CORS explica qué pasó. En el segundo, la documentación de ViaCEP muestra "erro": true, booleano, y la respuesta real trajo "true", texto. ^[12] Ese tipo de diferencia es justamente lo que revela probar la documentación.

7. Guarda y exporta

1. Haz clic en Salvar (guardar, Ctrl+S) y grábalo, por ejemplo, como viacep.html. Ese archivo ya es la documentación lista para enviar.
2. En Exportar ▾ → OpenAPI 3, la app descarga viacep-openapi.json. En la prueba de este tutorial, el archivo pasó la validación del paquete @apidevtools/swagger-parser, que comprueba el documento contra el esquema oficial de OpenAPI 3.0.
3. En Exportar ▾ → Testes Python (pruebas Python), la app descarga test_viacep.py. Ejecutada con pytest, la prueba pasó contra el ViaCEP real.

La interfaz

Barra superior

Título y versión de la API, el aviso ● não salvo (no guardado), el interruptor Visualizar / Editar (ver / editar) y los botones Salvar, Exportar ▾, Importar ▾ y Novo.

Barra lateral

El campo Filtrar endpoints…, que busca en el método, la ruta, el resumen y la tag; los endpoints agrupados por tag; y los schemas. En el modo edición añade Informações gerais, Autenticação, Tags, + Endpoint y + Schema.

Área central

En el modo ver, la documentación navegable con un panel de prueba en cada endpoint. En el modo edición, el formulario del elemento elegido en la barra lateral.

Avisos

Mensajes cortos aparecen unos segundos en la parte inferior de la pantalla: archivo guardado, parámetros detectados, error de importación.

En pantallas de menos de 860 px de ancho, la barra lateral desaparece y la navegación queda solo en el desplazamiento del área central.

Nombres de los botones

El modo Editar en detalle

Parámetros

Cada fila tiene nombre, ubicación (path, query, header, cookie), tipo, la marca de obligatorio, descripción y ejemplo. Un parámetro de ruta siempre es obligatorio: la especificación OpenAPI lo exige, y la app aplica la regla al exportar aunque la marca esté desactivada. ^[8] Los tipos integer, number y boolean hacen que el ejemplo se exporte como número o booleano, y no como texto.

Cuerpo y respuestas

El campo Content-Type sugiere los tipos más comunes. Los campos de ejemplo JSON se validan mientras escribes y tienen el botón Formatar JSON. Un ejemplo que no es JSON se acepta, pero se trata como texto.

Los endpoints marcados como obsoletos aparecen tachados, con la insignia “obsoleto”. Es la forma estándar de avisar que algo va a desaparecer, sin quitarlo de golpe.

Probar peticiones y CORS

El panel Testar requisição arma la URL con el servidor elegido, rellena los parámetros con los ejemplos, añade la credencial escrita y envía la petición desde el propio navegador. El resultado muestra el código, el tiempo, las cabeceras de la respuesta, el comando curl equivalente y el cuerpo formateado.

Por qué el navegador bloquea algunas llamadas

Por seguridad, el navegador solo deja que un script lea la respuesta de otro sitio si ese sitio lo autoriza, con la cabecera Access-Control-Allow-Origin. Ese mecanismo se llama CORS (Cross-Origin Resource Sharing). ^[11] Sin la autorización, el navegador entrega al script solo un error genérico, y la app muestra “Failed to fetch”.

Es lo que pasó con el código de 7 dígitos. Llamado fuera del navegador, ViaCEP respondió 400 Bad Request con una página HTML y sin la cabecera CORS; la consulta válida volvió con Access-Control-Allow-Origin: *. El error existía, pero el navegador lo ocultó.

Además, las peticiones con Authorization, con Content-Type: application/json o con métodos como PUT y DELETE van precedidas de una consulta OPTIONS, la preflight, que el servidor también debe aprobar. ^[11] Muchas API corporativas no abren CORS a cualquier origen.

Qué hacer cuando la prueba falla

1. Abre Comando curl, haz clic en Copiar curl y ejecútalo en la terminal. curl no es un navegador y no aplica CORS: ves el código y el cuerpo verdaderos.
2. Si curl funciona, la API está activa y el bloqueo es del navegador. Documenta con normalidad; lo único que no es posible es la prueba en la app.
3. Si curl también falla, revisa el servidor, la ruta, la credencial y la red.

Guardar

La app no usa servidor ni base de datos. La documentación está en un bloque JSON dentro del propio HTML, y guardar es escribir un HTML nuevo con ese bloque actualizado.

Lo que no se escribe: las credenciales escritas para probar, los valores cambiados en el panel de prueba y los resultados de las llamadas. Si intentas cerrar la pestaña con cambios pendientes, el navegador pide confirmación.

Importar

Muchas API ya tienen una especificación, generada por el propio framework del servidor. Importar evita escribirlo todo de nuevo.

Si el documento actual ya tiene endpoints, la app pregunta qué hacer:

• Mesclar (combinar) añade endpoints, tags, servidores y schemas que aún no existen. Un endpoint con el mismo método y ruta que otro existente se ignora. En la prueba, combinar ViaCEP con el ejemplo de Correios dio 5 endpoints.
• Substituir tudo (sustituir todo) descarta la documentación actual.

Cuando la especificación de origen no tiene ejemplo, la app crea uno a partir del schema, con valores genéricos como "string" y 0. Revisa esos ejemplos después de importar.

Exportar

Las pruebas en Python

El archivo generado empieza con las instrucciones de instalación y ejecución (en portugués). Cada prueba llama a un endpoint con los valores de ejemplo, comprueba el código de éxito documentado y verifica que los campos del ejemplo de respuesta existan en la respuesta real con el mismo tipo JSON.

pip install pytest requests
pytest -v test_viacep.py

• La URL base y las credenciales vienen de variables de entorno: API_BASE_URL, API_TOKEN, API_USER y API_PASS, o API_KEY. Así ninguna contraseña queda en el código.
• Los métodos que cambian datos (POST, PUT, PATCH, DELETE) solo se ejecutan con API_ALLOW_WRITE=1. Sin eso, aparecen como omitidos.
• Si la API tiene autenticación y el endpoint documenta la respuesta 401, la app crea también una prueba sin credenciales que espera 401.
• API_MAX_MS define un tiempo máximo de respuesta, si quieres vigilar la lentitud.

Prompts de IA

Una IA acelera las partes lentas de la documentación: encontrar endpoints repartidos por el código, convertir llamadas sueltas en una especificación, escribir descripciones y ampliar pruebas. También se equivoca con aplomo: inventa campos, adivina códigos de estado y describe comportamientos que la API no tiene. Trata su salida como un borrador y comprueba cada endpoint con el panel Testar requisição (probar petición), que habla con la API real. Para escribir mejores prompts, mira el tutorial de prompts.

Antes de pegar: quita tokens, contraseñas, claves de API, direcciones internas y datos de clientes de lo que va a la IA. Cámbialos por valores inventados y sigue la política de tu organización. La app solo habla con la API que pruebas, pero el servicio de IA recibe todo lo que pegues en él.

Cambia las partes entre corchetes y pega en la herramienta de IA que uses. Los prompts siguen el orden del trabajo: del 1 al 4 producen la documentación, y del 5 al 9 la revisan y la ponen en uso. Cada uno funciona por sí solo. Los nombres de los campos de la app siguen en portugués, como en pantalla.

1. Entrevistar antes de documentar

Cuando la API todavía está en la cabeza de quien la hizo. La IA pregunta en vez de suponer.

Eres un redactor técnico con experiencia en API REST y en la especificación OpenAPI.
Quiero documentar esta API: [describe en pocas frases qué hace y quién la usa].

Antes de escribir ninguna documentación, entrevístame:
- Haz una pregunta cada vez y espera mi respuesta.
- Cubre: la URL base de cada entorno; la forma de autenticación; cada recurso y las operaciones sobre él (método y ruta); los parámetros de ruta, de consulta y de cabecera, con tipo, obligatoriedad y un ejemplo; los cuerpos de las peticiones; las respuestas de éxito y de error, con el código y un ejemplo de cuerpo; la paginación; los límites de uso; lo que está obsoleto.
- Pregunta sobre todo por los errores: qué pasa con datos no válidos, sin credencial, sin permiso y con un recurso inexistente.
- No inventes respuestas. Si no lo sé, regístralo como pendiente.

Al final, entrega: una tabla de endpoints (método, ruta, resumen, tag), los parámetros y respuestas de cada uno, ejemplos de cuerpo en JSON y la lista de pendientes.

2. Encontrar los endpoints en el código

Para API ya programadas pero sin documentación. Pide el origen de cada elemento, lo que facilita comprobarlo.

A partir del código de abajo, reconstruye el contrato de la API REST que implementa.

Lenguaje y framework: [por ejemplo: Java con Spring, C# con ASP.NET, Node con Express, Python con FastAPI, ObjectScript con %CSP.REST]
Código:
[pega los controladores, las rutas o el UrlMap, y las clases de entrada y salida]

Entrega:
1. Tabla de endpoints: método, ruta (con {parámetros}), resumen, tag sugerida y el archivo y la línea de donde salió.
2. Para cada endpoint: parámetros (nombre, ubicación path, query, header o cookie, tipo, obligatorio), el cuerpo de la petición con un ejemplo en JSON, y las respuestas con código y ejemplo de cuerpo.
3. Los códigos de error que el código devuelve de verdad, y en qué situación.
4. Cómo se comprueba la autenticación.
5. Lagunas: retornos que dependen de código que no está aquí, excepciones no tratadas y comportamientos ambiguos, con una pregunta para cada uno.

No deduzcas lo que el código no muestra. Usa ejemplos inventados.

3. Generar el OpenAPI para importar en la app

Convierte lo que reuniste en un archivo que la app importa de una vez, en lugar de escribir endpoint por endpoint. El formato pedido es el que aprovecha el importador de la app.

Genera una especificación OpenAPI 3.0.3 en JSON para la API descrita al final. Se importará en API Docs, un editor que lee un subconjunto de OpenAPI.

Responde solo con el JSON, sin comentarios y sin bloques de código.

Usa solo estos elementos:
- "openapi": "3.0.3" e "info" con "title", "version" y "description". La descripción acepta Markdown sencillo: **negrita**, `código`, enlaces y listas con "- ".
- "servers": una lista con "url" (sin barra final) y "description".
- "tags": una lista con "name" y "description". Cada operación usa una sola tag.
- "paths": una operación por método (get, post, put, patch, delete), con "tags", "summary" (corto, empezando por un verbo), "description" y, si procede, "deprecated": true.
- "parameters": "name", "in" (path, query, header o cookie), "required", "description", "schema" con "type" (string, integer, number, boolean, array u object) y "example". Todo {parámetro} de la ruta necesita un parámetro con "in": "path" y "required": true.
- "requestBody" solo en post, put y patch: "description" y "content" con un único tipo de medio, normalmente "application/json", que contenga "example".
- "responses": para cada código, "description" y, cuando haya cuerpo, "content": {"application/json": {"example": ...}}. Incluye las respuestas de error que la API usa de verdad, con el cuerpo de error.
- "components.securitySchemes" con un único esquema: {"type": "http", "scheme": "bearer"}, {"type": "http", "scheme": "basic"} o {"type": "apiKey", "name": "...", "in": "header"}; y "security" en la raíz apuntando a él. Si la API es pública, omite los dos.
- "components.schemas" con los objetos principales.

Reglas:
- No inventes endpoints, campos ni códigos. Lo que falte va a "info.description", en una lista llamada Pendientes.
- Ejemplos realistas e inventados: nunca tokens, contraseñas, documentos ni correos reales.
- Los ejemplos de respuesta usan los mismos nombres de campo que los schemas.

Información de la API:
[pega el resultado del prompt 1, 2 o 4, la documentación existente o tu descripción]

4. Convertir llamadas reales en documentación

Cuando solo tienes llamadas que funcionan. En el navegador, abre las herramientas de desarrollo, pestaña Red, haz clic derecho en la petición y usa “Copiar como cURL”.

Abajo hay llamadas reales a una API, en cURL, con las respuestas que volvieron.
Ya cambié tokens y datos personales por valores inventados.

[pega cada cURL seguido del código de estado y del cuerpo de la respuesta]

Haz lo siguiente:
1. Agrupa las llamadas por recurso y deduce los endpoints: método y ruta, sustituyendo los valores que varían por {parámetros} con nombres claros (por ejemplo /pedidos/123 pasa a /pedidos/{id}).
2. Para cada endpoint, enumera los parámetros de ruta, de consulta y de cabecera, con tipo y un ejemplo sacado de las llamadas.
3. Usa los cuerpos reales como ejemplos de petición y de respuesta, acortando las listas largas a dos elementos.
4. Identifica la autenticación por las cabeceras (Authorization, X-API-Key u otra), sin repetir el valor.
5. Marca como “visto una vez” lo que aparece en una sola llamada, y enumera lo que falta saber: respuestas de error no observadas, parámetros opcionales y límites.

Entrégalo en tablas, listas para usar en el prompt 3.

5. Revisar la documentación

Una segunda lectura antes de publicar. Usa el archivo de Exportar ▾ → Markdown u OpenAPI 3.

Revisa la documentación de API de abajo como alguien que va a integrarse con ella por primera vez.

[pega el Markdown o el OpenAPI exportado por API Docs]

Comprueba y señala, endpoint por endpoint:
- Un método coherente con la acción: GET solo lee, POST crea, PUT sustituye, PATCH cambia una parte, DELETE elimina.
- Rutas hechas de sustantivos y con un patrón de nombres coherente (plural o singular, mayúsculas, guiones).
- Parámetros sin descripción, sin ejemplo, con el tipo equivocado, o parámetros de ruta que no aparecen en la ruta.
- Respuestas de error que faltan (400, 401, 403, 404, 422, 500) y errores devueltos con código 200.
- Ejemplos que no coinciden con el schema o entre sí.
- Datos en los ejemplos que parecen reales o sensibles: tokens, contraseñas, documentos, correos.
- Resúmenes vagos y descripciones que no dicen el efecto de la operación.

Entrega una tabla con: endpoint, problema, gravedad (alta, media, baja) y la corrección sugerida, como texto listo para pegar en la app. Termina con las tres correcciones más importantes.

6. Escribir textos para quien integra

Mejora resúmenes y descripciones sin cambiar el contrato. La salida tiene la forma de los campos de la app.

Reescribe los textos de esta documentación de API para quien va a integrarse con ella.

[pega el Markdown exportado o la lista de endpoints con resumen y descripción]
Idioma de los textos: [por ejemplo: portugués, español]

Para cada endpoint, entrega:
- Resumen: hasta 60 caracteres, empezando por un verbo (por ejemplo, Consultar un código postal).
- Descripción: hasta 4 frases. Qué hace la operación, cuándo usarla, efectos secundarios y una advertencia importante. Usa solo este Markdown: **negrita**, `código`, enlaces y listas con "- ".
- Descripción de cada parámetro: una frase con el formato esperado y un ejemplo.

Escribe también la descripción general de la API, con: para qué sirve, cómo autenticarse, dónde conseguir la credencial y un primer paso.

No cambies métodos, rutas, nombres de campos ni códigos. Si un texto actual está mal respecto al contrato, señálalo aparte.

7. Ampliar las pruebas en Python

El archivo de Exportar ▾ → Testes Python cubre el camino feliz. Este prompt añade los casos de error y de borde.

Abajo hay un archivo de pruebas pytest generado a partir de la documentación de una API, y la documentación.

Pruebas:
[pega el test_*.py exportado]
Documentación:
[pega el OpenAPI o el Markdown exportado]

Añade pruebas, sin cambiar las existentes:
- Para cada endpoint: parámetro obligatorio ausente, tipo equivocado, valor fuera de límite y recurso inexistente, esperando los códigos que define la documentación.
- Para endpoints con autenticación: sin credencial (401) y, si la documentación lo define, sin permiso (403).
- Para listas paginadas: primera página, página vacía y tamaño máximo.

Reglas:
- Reutiliza la fixture api y las funciones url, check_status, json_of y assert_shape del archivo.
- Lee la URL y las credenciales de las variables de entorno ya usadas; nunca escribas secretos en el código.
- Marca con @WRITE toda prueba que use POST, PUT, PATCH o DELETE.
- Si la documentación no dice qué código esperar, no lo inventes: crea la prueba con pytest.skip y el motivo.

Entrega solo el código nuevo, listo para pegar al final de la clase correspondiente, y una lista de lo que quedó sin prueba.

8. Diagnosticar una llamada que falló

Para cuando el panel de prueba muestra un error y no sabes si el problema es la API, la red, el navegador o la documentación.

Una llamada a una API falló. Ayúdame a encontrar la causa.

Mensaje en el navegador: [por ejemplo: Failed to fetch, o el código y el cuerpo mostrados]
Comando curl (sin el token): [pega el curl copiado del panel Testar requisição]
Resultado del curl en la terminal: [código de estado, cabeceras y cuerpo, o el mensaje de error]
Lo que la documentación dice que debería pasar: [código y cuerpo esperados]

Clasifica la causa más probable entre: bloqueo de CORS en el navegador, red o DNS, certificado HTTPS, credencial ausente o caducada, falta de permiso, petición mal formada, recurso inexistente, error del servidor, o documentación desactualizada.

Explica en qué evidencia te basaste, indica la próxima prueba que confirma la hipótesis y, si procede, qué corregir en la documentación. No supongas nada que las evidencias no muestren.

9. Implementar la clase generada para InterSystems IRIS

La exportación InterSystems IRIS crea rutas y métodos que devuelven la respuesta de ejemplo, con marcas TODO. Este prompt pide la implementación manteniendo el contrato.

Abajo hay una clase ObjectScript que extiende %CSP.REST, generada a partir de la documentación de una API. Cada método devuelve la respuesta de ejemplo y tiene un comentario TODO.

Clase:
[pega el .cls exportado]
Reglas de negocio y datos:
[describe las tablas o clases persistentes involucradas y qué debe hacer cada endpoint]

Implementa los métodos marcados con TODO:
- No cambies el UrlMap, los nombres de los métodos ni los códigos y campos documentados.
- Usa %DynamicObject y %DynamicArray para armar el JSON de respuesta.
- En SQL, usa parámetros (? o :variable); nunca concatenes texto del usuario en la consulta.
- Responde con ..Erro(código, mensaje) en los errores documentados: 400 para entrada no válida y 404 para recurso inexistente.
- Mantén el bloque Try/Catch existente.

Entrega la clase completa y, después, la lista de suposiciones que hiciste sobre los datos.

Cómo importar el JSON del prompt 3

1. Copia la respuesta de la IA en un editor de texto y guárdala con la extensión .json, por ejemplo mi-api.json.
2. En la app, usa Importar ▾ → Swagger / OpenAPI, o arrastra el archivo a la ventana. Si ya hay endpoints, elige Mesclar (combinar) o Substituir tudo (sustituir todo).
3. Pasa por el modo Editar: comprueba rutas, parámetros y ejemplos, y lee los pendientes en la descripción general.
4. En el modo Visualizar (ver), prueba cada endpoint con Testar requisição. Donde la respuesta real difiera del ejemplo, vale la respuesta real.
5. Haz clic en Salvar (guardar).

Para API grandes, pide un JSON por tag e impórtalos uno a uno con Mesclar: la app añade lo nuevo e ignora los endpoints con el mismo método y ruta.

Errores comunes

• “Failed to fetch: la API se cayó”

  Casi siempre es CORS o la red. Ejecuta curl antes de concluir nada.

• Credenciales en el ejemplo o en la descripción

  El archivo HTML está hecho para enviarse. Token y contraseña van solo en los campos del panel de prueba, que no se guardan.

• Ejemplos inventados

  Un ejemplo escrito de memoria se aleja de la API real. Haz la llamada y usa la respuesta verdadera como ejemplo.

• Documentar solo el éxito

  Quien integra necesita saber qué vuelve cuando algo sale mal. Documenta 400, 401, 404 y el cuerpo de error.

• Cuerpo en un GET

  El contenido en un GET no tiene significado definido en HTTP. Para filtros, usa parámetros de consulta.

• Olvidar guardar

  Mientras aparezca “● não salvo”, no se ha escrito nada. Usa Ctrl+S.

Limitaciones y solución de problemas

La app cubre lo esencial de OpenAPI, no la especificación entera. Lo que queda fuera:

• Una sola forma de autenticación para toda la API. No hay autenticación por endpoint, ni OAuth 2 con flujos, ni más de un esquema. Al importar, solo se aprovecha el primer esquema, y OAuth 2 pasa a Bearer.
• Los parámetros tienen solo tipo, sin formato, lista de valores, mínimo ni máximo.
• Los ejemplos de respuesta se exportan siempre como application/json, y las cabeceras de respuesta no se documentan.
• Los schemas están en una lista propia; los endpoints no apuntan a ellos con $ref.
• Al importar, se pierden los parámetros formData de Swagger 2.0 y las cabeceras de respuesta; de varias tags o varios ejemplos, queda el primero.
• El YAML lo lee un intérprete propio de la app, que cubre el uso común. Si un archivo YAML falla, conviértelo a JSON e impórtalo de nuevo.

Repaso rápido

Intenta responder antes de abrir cada pregunta.

Referencias

1. Giovani Perotto Mesquita, “API Docs”, aplicación en un único archivo HTML (interfaz en portugués), giovanipm.github.io/api-docs.html.
2. Roy Thomas Fielding (en inglés), “Architectural Styles and the Design of Network-based Software Architectures”, tesis doctoral, Universidad de California en Irvine, 2000, capítulo 5, consultado el 11 de noviembre de 2026, ics.uci.edu/~fielding/pubs/dissertation/top.htm.
3. IETF (en inglés), RFC 9110, “HTTP Semantics”, junio de 2022, secciones 9 (métodos) y 15 (códigos de estado), consultado el 11 de noviembre de 2026, rfc-editor.org/rfc/rfc9110.
4. IETF (en inglés), RFC 3986, “Uniform Resource Identifier (URI): Generic Syntax”, 2005, consultado el 11 de noviembre de 2026, rfc-editor.org/rfc/rfc3986.
5. IETF (en inglés), RFC 8259, “The JavaScript Object Notation (JSON) Data Interchange Format”, 2017, consultado el 11 de noviembre de 2026, rfc-editor.org/rfc/rfc8259.
6. IETF (en inglés), RFC 7617, “The 'Basic' HTTP Authentication Scheme”, 2015, consultado el 11 de noviembre de 2026, rfc-editor.org/rfc/rfc7617.
7. IETF (en inglés), RFC 6750, “The OAuth 2.0 Authorization Framework: Bearer Token Usage”, 2012, consultado el 11 de noviembre de 2026, rfc-editor.org/rfc/rfc6750.
8. OpenAPI Initiative (en inglés), “OpenAPI Specification v3.0.3”, 20 de febrero de 2020, incluido el apéndice A, “Revision History”, consultado el 11 de noviembre de 2026, spec.openapis.org/oas/v3.0.3.html.
9. OpenAPI Initiative (en inglés), “OpenAPI Specification v3.2.0”, septiembre de 2025, consultado el 11 de noviembre de 2026, spec.openapis.org/oas/v3.2.
10. Wikipedia (en inglés), “OpenAPI Specification”, consultado el 11 de noviembre de 2026, en.wikipedia.org/wiki/OpenAPI_Specification. Divergencia: Wikipedia fecha la creación de Swagger en 2010 y el anuncio de la OpenAPI Initiative en noviembre de 2015; el historial de revisiones de la especificación [8] registra la versión 1.0 el 10 de agosto de 2011 y la donación el 31 de diciembre de 2015.
11. MDN Web Docs (en inglés), “Cross-Origin Resource Sharing (CORS)”, consultado el 11 de noviembre de 2026, developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS.
12. ViaCEP (en portugués), página del webservice, consultado el 11 de noviembre de 2026, viacep.com.br. Divergencia: la página muestra "erro": true para un código inexistente; la llamada real de este tutorial, el 11 de noviembre de 2026, devolvió "erro": "true".
13. Postman (en inglés), “Postman Collection Format v2.1.0”, esquema JSON, consultado el 11 de noviembre de 2026, schema.getpostman.com/json/collection/v2.1.0/collection.json.
14. pytest (en inglés), documentación, consultado el 11 de noviembre de 2026, docs.pytest.org.
15. Requests (en inglés), “Requests: HTTP for Humans”, documentación, consultado el 11 de noviembre de 2026, requests.readthedocs.io.
16. InterSystems (en inglés), “Creating REST Services”, documentación de InterSystems IRIS, consultado el 11 de noviembre de 2026, docs.intersystems.com/irislatest/csp/docbook/Doc.View.cls?KEY=GREST.
17. MDN Web Docs (en inglés), “File System API”, consultado el 11 de noviembre de 2026, developer.mozilla.org/en-US/docs/Web/API/File_System_API.
18. IETF (en inglés), RFC 5789, “PATCH Method for HTTP”, 2010, consultado el 11 de noviembre de 2026, rfc-editor.org/rfc/rfc5789.