Configurar vários exemplos de corpo do pedido

O Apidog suporta a configuração de vários exemplos para corpos de pedidos dos tipos JSON, XML, Raw e MsgPack. Esta funcionalidade é útil para:

Configurar exemplos para diferentes cenários de negócio: Por exemplo, pedidos normais vs. pedidos de exceção.

Conformidade com as especificações OAS 3.0/3.1: Suporta a exportação de especificações OpenAPI padrão.

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

Configurar vários exemplos de corpo do pedido

É necessária a versão 2.7.0 ou posterior do Apidog.

Criar um novo exemplo de corpo do pedido

Aceda à página Edit da documentação do seu endpoint.

Localize a secção Request Body.

Clique no botão + Add para criar um novo exemplo de corpo do pedido.

Configurar o exemplo de corpo do pedido

Nome do exemplo (opcional): Se for deixado em branco, o valor predefinido será Example 1, Example 2, etc.

Valor do exemplo (obrigatório): Forneça os dados de exemplo reais para o corpo do pedido.

Descrição (opcional): Adicione uma descrição para explicar o exemplo. Suporta formatação Markdown para texto enriquecido.

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

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

Guardar e utilizar o exemplo de corpo do pedido

Depois de guardar o exemplo, este fica disponível para utilização. Durante a depuração, pode selecionar facilmente diferentes exemplos para testar os seus endpoints.

Utilizar exemplo de corpo do pedido durante a depuração

TIP

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

Extrair parâmetros do pedido como exemplos

Durante a depuração, se tiver configurado manualmente o corpo do pedido e pretender guardá-lo como exemplo, basta clicar em: Extract > Extract to "Request Example".

Escolher a opção de extração

Ser-lhe-á pedido que escolha como guardar os parâmetros do pedido:

Substituir o exemplo: Substituir um exemplo guardado anteriormente.

Novo exemplo: Guardá-lo como um exemplo totalmente novo.

TIP

O valor de depuração atual será automaticamente preenchido no exemplo por predefinição.

Cenários de utilização

Utilizar exemplos de corpo do pedido durante a depuração

Aceda à página Run da documentação do endpoint e localize a secção Auto-generate.

Clique no menu pendente para selecionar um exemplo de corpo do pedido. O exemplo será preenchido automaticamente.

Alternar exemplos de corpo do pedido durante a depuração

Pode alternar entre exemplos em tempo real e enviar pedidos com o exemplo selecionado.

Definições avançadas

Clique no ícone pendente junto a Auto-generate para aceder às seguintes opções:

EXAMPLES: Escolha entre exemplos de corpo do pedido predefinidos.

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

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

Apresentação da documentação

Para um único exemplo de corpo do pedido: Apresentado numa vista simplificada sem mostrar o nome do exemplo.

Para vários exemplos de corpo do pedido: Permite alternar entre exemplos numa disposição lado a lado, apresentando nomes de exemplos e descrições em Markdown.

Apresentação de exemplos de corpo do pedido

Ordem de apresentação

A ordem de apresentação dos exemplos de corpo do pedido segue esta prioridade:

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

Os itens não vazios são apresentados 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 do pedido.

Regras de exportação:

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

Quando não preenchida: Números de série (a começar em 1) são automaticamente utilizados 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

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

Configuração: Introduza pares chave-valor JSON no campo 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 ativar vários exemplos de corpo do pedido em projetos antigos?

Não é necessária qualquer ação manual! Quando adiciona um segundo exemplo de corpo do pedido a um endpoint existente, o sistema atualiza automaticamente o formato para suportar vários exemplos.

Como lidar com vários exemplos de corpo do pedido ao exportar OAS?

A ordem dos exemplos de corpo do pedido muda na OAS exportada?

Como tornar os nomes dos exemplos exportados mais intuitivos?

Configurar vários exemplos de corpo do pedido

Configurar vários exemplos de corpo do pedido#

Extrair parâmetros do pedido como exemplos#

Cenários de utilização#

Utilizar exemplos de corpo do pedido durante a depuração#

Apresentação da documentação#

Conformidade com OAS#

Chave OAS#

Extensões OAS#

Perguntas frequentes#

Configurar vários exemplos de corpo do pedido

Extrair parâmetros do pedido como exemplos

Cenários de utilização

Utilizar exemplos de corpo do pedido durante a depuração

Apresentação da documentação

Conformidade com OAS

Chave OAS

Extensões OAS

Perguntas frequentes