O Apidog suporta a adição de múltiplos exemplos de corpo de requisição para cada endpoint, tornando sua documentação de API mais útil e compatível com as especificações do OpenAPI. Esse recurso permite que você mostre diferentes maneiras de estruturar requisições para o mesmo endpoint, o que ajuda os desenvolvedores a entender como usar sua API em várias situações.
Os exemplos de corpo de requisição são úteis porque:
- Mostram aos desenvolvedores exatamente como formatar suas requisições
- Demonstram diferentes casos de uso para o mesmo endpoint
- Tornam o teste mais fácil ao fornecer estruturas de requisição prontas para uso
- Garantem que sua documentação siga os padrões do OpenAPI
Você pode adicionar quantos forem necessários para cobrir todos os cenários possíveis.
Passo a Passo: Adicionando Seu Primeiro Exemplo de Corpo de Requisição
Adicionar exemplos de corpo de requisição no Apidog é simples. Veja como começar:
1. Abra seu projeto de API no Apidog (versão 2.7.0 ou superior)
2. Navegue até o endpoint onde você deseja adicionar exemplos
3. Clique na aba "Editar" para acessar o editor de documentação e Role até a seção "Corpo da Requisição"
4. Clique em "Adicionar Exemplo" para criar um novo exemplo
5. Preencha os detalhes do exemplo:
- Nome do Exemplo: Dê ao seu exemplo um nome claro (por exemplo, "Requisição Padrão")
- Valor do Exemplo: Insira o JSON, XML ou outros dados formatados reais
- Descrição: Explique quando usar este exemplo (suporta Markdown)
- Chave OAS: Forneça um identificador para exportação OpenAPI (opcional, mas recomendado)
- Extensões OAS: Adicione quaisquer campos personalizados necessários para exportação (opcional)
6. Clique em "Salvar" para criar o exemplo
O nome do exemplo ajuda os usuários a identificar o propósito de cada exemplo. Se você deixá-lo em branco, o Apidog nomeará automaticamente como "Exemplo 1", "Exemplo 2", etc.
O valor do exemplo deve mostrar uma estrutura de requisição válida. Para tipos de conteúdo JSON, o Apidog fornece um editor estruturado para ajudar a garantir a formatação válida.
O campo de descrição é onde você pode explicar quando e por que alguém usaria esta estrutura de requisição específica. Usar Markdown aqui pode tornar suas explicações mais claras.
A Chave OAS é importante se você planeja exportar sua documentação para o formato OpenAPI. Esta chave se torna o identificador do exemplo na especificação exportada.
Criando Múltiplos Exemplos para Diferentes Cenários
Após adicionar seu primeiro exemplo, você desejará criar exemplos adicionais para diferentes casos de uso:
- Clique novamente no botão "+ Adicionar" para criar outro exemplo
- Dê-lhe um nome distinto que identifique claramente o cenário (por exemplo, "Requisição Mínima")
- Insira o valor do exemplo para este cenário específico
- Adicione uma descrição detalhada explicando quando usar este exemplo
- Configure a Chave OAS e Extensões conforme necessário
- Clique em "Salvar" para adicionar o exemplo
- Repita este processo para todos os cenários relevantes
Ao criar múltiplos exemplos, considere cobrir estes cenários comuns:
- Requisição Padrão: A forma típica de usar o endpoint
- Requisição Mínima: A estrutura de requisição válida mais simples
- Requisição Completa: Uma requisição utilizando todos os campos possíveis
- Caso Especial: Exemplos para cenários de negócios únicos
Cada exemplo deve mostrar uma forma diferente de usar o endpoint. Isso ajuda os desenvolvedores a entenderem a gama completa de possibilidades ao trabalhar com sua API.
O Apidog exibe os exemplos em uma ordem específica:
- Exemplos com nomes aparecem antes de exemplos sem nome
- Exemplos com Chaves OAS são exibidos antes daqueles sem
- Exemplos sem nomes ou Chaves OAS são ordenados por seus números de série
Para que seus exemplos mais importantes apareçam primeiro, dê a eles nomes claros e Chaves OAS.
Usando Exemplos de Corpo de Requisição para Testes
Um dos melhores recursos de múltiplos exemplos de corpo de requisição é como eles simplificam os testes:
- Navegue até a página "Executar" do seu endpoint
- Encontre a seção "Geração Automática" na configuração da requisição
- Clique no menu suspenso para ver todos os exemplos disponíveis
- Selecione o exemplo que você deseja testar
- O corpo da requisição será preenchido automaticamente com o exemplo selecionado
- Clique em "Enviar" para testar o endpoint com este exemplo
Isso facilita o teste de diferentes cenários sem precisar digitar ou colar manualmente diferentes estruturas de requisição. Você pode alternar rapidamente entre exemplos para ver como sua API lida com várias entradas.
O Apidog também permite que você crie exemplos a partir de suas sessões de teste:
- Configure um corpo de requisição na página "Executar"
- Clique no botão "Extrair"
- Selecione "Extrair para Exemplo de Requisição"
- Escolha criar um novo exemplo ou atualizar um existente
- Seu corpo de requisição atual será salvo como um exemplo
Isso é útil quando você encontrou uma estrutura de requisição que funciona durante o teste e deseja salvá-la para referência futura ou documentação.
Garantindo a Compatibilidade com OpenAPI em Seus Exemplos
Os exemplos de corpo de requisição do Apidog são projetados para funcionar perfeitamente com as especificações do OpenAPI. Quando você exporta sua documentação de API, todos os seus exemplos são formatados corretamente de acordo com os padrões OAS 3.0/3.1.
Veja como os exemplos são tratados durante a exportação:
- Cada exemplo é incluído na especificação exportada
- Os nomes dos exemplos vêm da Chave OAS, se fornecida (ou números de série se não)
- As descrições dos exemplos são preservadas no formato exportado
- Quaisquer Extensões OAS personalizadas são incluídas na exportação
A especificação OpenAPI exportada incluirá seus exemplos em uma estrutura como esta:
"examples": {
"standard_request": {
"value": {
"name": "John Doe",
"id": "12345",
"email": "john.doe@example.com"
},
"summary": "Requisição Padrão",
"description": "Esta é uma requisição padrão com todos os campos obrigatórios."
},
"minimal_request": {
"value": {
"id": "12345"
},
"summary": "Requisição Mínima",
"description": "Esta é uma requisição mínima com apenas o campo ID obrigatório."
}
}
Para garantir a melhor compatibilidade com o OpenAPI:
- Use Chaves OAS significativas para todos os exemplos
- Forneça descrições claras que expliquem o propósito de cada exemplo
- Revise suas especificações exportadas para verificar se tudo está correto
Isso garante que seus exemplos permaneçam valiosos não apenas dentro do Apidog, mas também quando compartilhados através das especificações OpenAPI.
Melhores Práticas para Exemplos de Corpo de Requisição
Para obter o máximo valor de múltiplos exemplos de corpo de requisição, siga estas melhores práticas:
Crie Conjuntos de Exemplos Abrangentes
Inclua exemplos que cubram:
- Uso básico com apenas os campos obrigatórios
- Uso típico com campos opcionais comumente usados
- Uso completo demonstrando todos os campos possíveis
- Casos extremos que demonstrem situações especiais
Use Nomes Claros
- Dê a cada exemplo um nome descritivo que indique seu propósito
- Use padrões de nomenclatura consistentes em diferentes endpoints
- Evite nomes genéricos como "Exemplo 1" que não expliquem o conteúdo
Escreva Descrições Úteis
- Explique quando e por que alguém usaria cada exemplo
- Mencione quaisquer considerações especiais para esta estrutura de requisição
- Use formatação Markdown para facilitar a leitura das descrições
- Inclua respostas esperadas quando relevante
Organize Exemplos Logicamente
- Coloque os cenários mais comuns primeiro
- Agrupe exemplos relacionados juntos
- Remova exemplos desatualizados para evitar confusão
- Atualize exemplos quando sua API mudar
Use Chaves OAS de Forma Eficiente
- Escolha chaves significativas que descrevam o propósito do exemplo
- Use nomenclatura de chave consistente em sua API
- Evite caracteres especiais que possam causar problemas nas exportações
Seguindo essas práticas, você criará exemplos de corpo de requisição que realmente ajudam os desenvolvedores a entender e usar sua API de forma eficaz.
Conclusão
Adicionar múltiplos exemplos de corpo de requisição no Apidog é uma maneira simples, mas poderosa, de melhorar sua documentação de API. Ao mostrar diferentes maneiras de estruturar requisições para o mesmo endpoint, você ajuda os desenvolvedores a entender como usar sua API em várias situações.
O processo passo a passo é simples:
- Navegue até seu endpoint e clique em "Editar"
- Role até a seção Corpo da Requisição e clique em "+ Adicionar"
- Configure seu exemplo com um nome, valor, descrição e Chave OAS
- Repita para cenários adicionais
- Use seus exemplos para testes e documentação
Com exemplos adequados em seu lugar, sua API se torna mais fácil de entender, testar e implementar. Isso leva a uma adoção mais rápida, menos perguntas de suporte e uma melhor experiência para os desenvolvedores.
Comece a adicionar múltiplos exemplos de corpo de requisição à sua documentação do Apidog hoje para ver os benefícios por si mesmo e para seus usuários de API.