Configurar vários exemplos de corpo da requisição

O Apidog permite configurar vários exemplos para corpos de requisição dos tipos JSON, XML, Raw e MsgPack. Esse recurso é útil para:

Configurar exemplos para diferentes cenários de negócios: por exemplo, requisições normais versus requisições de exceção.

Conformidade com as especificações OAS 3.0/3.1: permite exportar especificações OpenAPI padrão.

Alternar rapidamente entre exemplos: útil durante a depuração e testes automatizados.

Configurar vários exemplos de corpo da requisição

É necessário usar o Apidog versão 2.7.0 ou posterior.

Criar um novo exemplo de corpo da requisição

Acesse a página Edit da documentação do seu endpoint.

Localize a seção Request Body.

Clique no botão + Add para criar um novo exemplo de corpo da requisição.

Criando um novo exemplo de corpo da requisição

Configurar o exemplo de corpo da requisição

Nome do exemplo (opcional): se deixado em branco, o valor padrão será Example 1, Example 2 etc.

Valor do exemplo (obrigatório): forneça os dados reais de exemplo para o corpo da requisição.

Descrição (opcional): adicione uma descrição para explicar o exemplo. Compatível com formatação Markdown para texto enriquecido.

Chave OAS (opcional): usada ao exportar especificações OpenAPI. Se não for fornecida, um número de série será usado em seu lugar.

Extensões OAS (campos personalizados): se fornecidas, serão mantidas durante a exportação.

Configurar exemplo de corpo da requisição

Salvar e usar o exemplo de corpo da requisição

Depois de salvar o exemplo, ele ficará disponível para uso. Durante a depuração, você pode selecionar facilmente diferentes exemplos para testar seus endpoints.

Usar exemplo de corpo da requisição durante a depuração

TIP

Para corpos de requisição do tipo Raw, apenas o primeiro valor de exemplo é exibido durante a depuração.

Extrair parâmetros da requisição como exemplos

Durante a depuração, se você tiver configurado manualmente o corpo da requisição e quiser salvá-lo como um exemplo, basta clicar em: Extract > Extract to "Request Example".

Escolher a opção de extração

Você será solicitado a escolher como salvar os parâmetros da requisição:

Substituir o exemplo: substitua um exemplo salvo anteriormente.

Novo exemplo: salve como um exemplo totalmente novo.

TIP

O valor atual da depuração será preenchido automaticamente no exemplo por padrão.

Cenários de uso

Usar exemplos de corpo da requisição durante a depuração

Acesse a página Run da documentação do endpoint e localize a seção Auto-generate.

Clique no menu suspenso para selecionar um exemplo de corpo da requisição. O exemplo será preenchido automaticamente.

Alternar exemplos de corpo da requisição durante a depuração

Você pode alternar entre exemplos em tempo real e enviar requisições com o exemplo selecionado.

Configurações avançadas

Clique no ícone suspenso ao lado de Auto-generate para acessar as seguintes opções:

EXAMPLES: escolha entre exemplos predefinidos de corpo da requisição.

Generate Each Time: gere automaticamente valores aleatórios com base em regras de mock.

Auto-generation Preference: para configurações mais avançadas, consulte Gerar requisições.

Exibição da documentação

Para um único exemplo de corpo da requisição: exibido em uma visualização simplificada, sem mostrar o nome do exemplo.

Exibição de um único corpo da requisição

Para vários exemplos de corpo da requisição: permite alternar entre exemplos em um layout lado a lado, exibindo nomes de exemplos e descrições em Markdown.

Exibição de exemplos de corpo da requisição

Ordem de exibição

A ordem de exibição dos exemplos de corpo da requisição segue esta prioridade:

Nome do exemplo > Chave OAS > Número de série (incrementado automaticamente a partir de 1).

Itens não vazios são exibidos primeiro.

Conformidade com OAS

Chave OAS

A chave OAS controla os nomes dos campos dos exemplos ao exportar especificações OpenAPI.

Configuração: preencha a Chave OAS para os exemplos de corpo da requisição.

Configurar chave OAS do corpo da requisição

Regras de exportação:

Quando preenchida: a chave OAS fornecida é usada como o nome do campo dentro do objeto examples.

Quando não preenchida: números de série (começando em 1) são usados automaticamente como nomes de campos.

Quando preenchida

Quando não preenchida:

 "examples": {
   "example1": {
      "value": {
        "name": "Blake Keeling",
        "id": "165061",
        "email": "Blake.Keeling@gmail.com"
      },
      "summary": "example1",
      "description": "This is`example 1`"
    },
    "example2": {
       "value": {
        "name": "Jolie Kutch",
        "id": "138164",
        "email": "Jolie_Kutch@hotmail.com"
      },
      "summary": "example 2",
      "description": "This is`example 2`"
    }
  }

"examples": {
   "1": {
     "value": {
       "name": "Blake Keeling",
       "id": "165061",
       "email": "Blake.Keeling@gmail.com"
     },
     "summary": "example1",
     "description": "This is`example 1`"
   },
    "2": {
      "value": {
       "name": "Jolie Kutch",
       "id": "138164",
       "email": "Jolie_Kutch@hotmail.com"
     },
     "summary": "example 2",
     "description": "This is`example 2`"
   }
 }

Extensões OAS

Você pode adicionar extensões personalizadas da Especificação OpenAPI (OAS) aos exemplos.

Configuração: insira pares chave-valor JSON no campo de extensão OAS.

{
  "x-demo": true,
  "x-scenario": "error_case"
}

Efeito da exportação: as extensões OAS personalizadas serão totalmente preservadas e incluídas nas especificações OpenAPI exportadas.

"examples": {
    "example1": {
      "x-demo": true,
      "x-scenario": "error_case",
      "value": {
         "name": "Blake Keeling",
         "id": "165061",
         "email": "Blake.Keeling@gmail.com"
      },
      "summary": "example1",
      "description": "This is`example 1`"
    }
}

Perguntas frequentes

Como habilitar vários exemplos de corpo da requisição em projetos antigos?

Nenhuma ação manual é necessária! Quando você adiciona um segundo exemplo de corpo da requisição a um endpoint existente, o sistema atualiza automaticamente o formato para oferecer suporte a vários exemplos.

Como lidar com vários exemplos de corpo da requisição ao exportar OAS?

A ordem dos exemplos de corpo da requisição mudará na OAS exportada?

Como tornar os nomes dos exemplos exportados mais amigáveis?

Configurar vários exemplos de corpo da requisição

Configurar vários exemplos de corpo da requisição#

Extrair parâmetros da requisição como exemplos#

Cenários de uso#

Usar exemplos de corpo da requisição durante a depuração#

Exibição da documentação#

Conformidade com OAS#

Chave OAS#

Extensões OAS#

Perguntas frequentes#

Configurar vários exemplos de corpo da requisição

Extrair parâmetros da requisição como exemplos

Cenários de uso

Usar exemplos de corpo da requisição durante a depuração

Exibição da documentação

Conformidade com OAS

Chave OAS

Extensões OAS

Perguntas frequentes