Criar um proxy de API a partir de uma especificação OpenAPI

Esta página aplica-se ao Apigee e ao Apigee Hybrid.

Veja a documentação do Apigee Edge.

O que vai aprender

Neste tutorial, vai aprender a:

  • Crie um proxy de API do Apigee a partir de uma especificação OpenAPI.
  • Chame o proxy de API através do cURL.
  • Adicione uma política a um fluxo condicional.
  • Teste a invocação da política através do cURL.

Vai saber como criar um proxy de API do Apigee a partir de uma especificação OpenAPI usando a IU do Apigee. Quando chama o proxy de API com um cliente HTTP, como o cURL, o proxy de API envia o pedido para o serviço de destino simulado do Apigee.

Acerca da Open API Initiative

Open API Initiative

"A Open API Initiative (OAI) está focada na criação, evolução e promoção de um formato de descrição de API neutro em relação ao fornecedor com base na especificação Swagger." Para mais informações sobre a Open API Initiative, consulte A especificação OpenAPI.

Uma especificação OpenAPI usa um formato padrão para descrever uma API RESTful. Escrita no formato JSON ou YAML, uma especificação OpenAPI é legível por computador, mas também é fácil de ler e compreender para os humanos. A especificação descreve elementos de uma API, como o respetivo caminho base, caminhos e verbos, cabeçalhos, parâmetros de consulta, operações, tipos de conteúdo, descrições de respostas e muito mais. Além disso, uma especificação da OpenAPI é frequentemente usada para gerar documentação da API.

Acerca do serviço de destino simulado do Apigee

O serviço de destino simulado do Apigee usado neste tutorial está alojado no Apigee e devolve dados simples. Não requer uma chave da API nem um token de acesso. Na verdade, pode aceder ao mesmo num navegador de Internet. Experimente clicando no seguinte:

http://mocktarget.apigee.net

O serviço de destino devolve a saudação Hello, guest!

Para obter informações sobre o conjunto completo de APIs suportadas pelo serviço de destino simulado, consulte as APIs de exemplo do Apigee

Requisitos

  • Antes de começar, tem de concluir os passos descritos no artigo Vista geral e pré-requisitos.
  • Uma especificação OpenAPI. Neste tutorial, vai usar a mocktarget.yaml especificação OpenAPI que descreve o serviço de destino simulado do Apigee, http://mocktarget.apigee.net. Para mais informações, consulte apigee/api-platform-samples.
  • O cURL instalado no seu computador para fazer chamadas de API a partir da linha de comandos ou um navegador de Internet.

Crie o proxy de API

Para criar o proxy de API a partir de uma especificação OpenAPI:

Apigee na Cloud Console

  1. Na Google Cloud consola, aceda à página Desenvolvimento de proxy > Proxies de API.

    Aceda aos proxies de API

  2. No painel Proxies de API, clique em + Criar.
  3. No painel Criar um proxy, em Modelo de proxy > Modelo de especificação da API OpenAPI, selecione Proxy inverso (mais comum).
  4. Navegue para o seguinte URL no navegador de Internet: 
    https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget3.0.yaml
  5. Clique com o botão direito do rato no código apresentado e selecione Guardar como.
  6. Clique em Guardar para guardar o mocktarget3.0.yaml na localização pretendida.
  7. No campo Especificações da API OpenAPI, clique no botão Procurar.
  8. Navegue até ao ficheiro mocktarget3.0.yaml e clique em Abrir.
  9. Clicar em Seguinte.
  10. O passo Detalhes do proxy do assistente Criar proxy preenche automaticamente os respetivos campos com valores extraídos diretamente da especificação OpenAPI.

    11. A tabela seguinte descreve os valores predefinidos pré-preenchidos através da especificação OpenAPI:

    Campo Descrição Predefinição
    Nome do proxy Nome do proxy de API. Por exemplo: Mock-Target-API. Propriedade title da especificação OpenAPI com espaços substituídos por travessões
    Caminho base Componente do caminho que identifica de forma exclusiva este proxy de API na organização. O URL público deste proxy de API é composto pelo nome do seu domínio externo ou interno e por este caminho base. Por exemplo: http://apitest.acme.com/mock-target-api Conteúdo do campo Nome convertido para minúsculas
    Descrição Descrição do proxy de API. description da propriedade da especificação OpenAPI
    Destino (API existente) URL de destino invocado em nome deste proxy de API. Pode usar qualquer URL acessível através da Internet aberta. Por exemplo: http://mocktarget.apigee.net servers da propriedade da especificação OpenAPI

    Segue-se um excerto da especificação OpenAPI que mostra as propriedades usadas para pré-preencher os campos.

          openapi: 3.0.0
      info:
        description: OpenAPI Specification for the Apigee mock target service endpoint.
        version: 1.0.0
        title: Mock Target API
      paths:
        /:
          get:
            summary: View personalized greeting
            operationId: View a personalized greeting
            description: View a personalized greeting for the specified or guest user.
            parameters:
              - name: user
                in: query
                description: Your user name.
                required: false
                schema:
                  type: string
            responses:
              "200":
                description: Success
      ...
      servers:
        - url: http://mocktarget.apigee.net
        - url: https://mocktarget.apigee.net
      ...
  11. No passo Detalhes do proxy, edite o campo Descrição da seguinte forma: 
    API proxy for the Apigee mock target service endpoint.
  12. Clicar em Seguinte.
  13. No passo Fluxos, certifique-se de que todas as operações estão selecionadas.
  14. Clicar em Seguinte.
  15. No passo Implementar, selecione um ou mais ambientes e clique em OK.
  16. Clique em Criar.

IU do Apigee Classic

  1. Selecione Develop > API Proxies e, no painel Proxies, selecione o ambiente para o proxy.
  2. Clique em Proxies de API na janela principal.

    Em alternativa, pode selecionar Desenvolver > Proxies de API na barra de navegação do lado esquerdo.

    Clique em Proxies de API na página de destino

  3. Clique em Criar novo.

    Adicione um proxy de API

  4. No assistente Criar proxy, clique em Usar especificação OpenAPI para o modelo Proxy inverso (mais comum).

    Crie um tipo de proxy
  5. Clique em URL e introduza as seguintes informações:

    URL da especificação OpenAPI: caminho para o conteúdo não processado no GitHub para a especificação OpenAPI no campo URL: 

    https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget3.0.yaml
  6. Clique em Selecionar.

    É apresentada a página Detalhes do proxy no assistente Criar proxy. Os campos são pré-preenchidos com valores definidos na especificação OpenAPI, conforme mostrado na figura seguinte:

    A tabela seguinte descreve os valores predefinidos pré-preenchidos através da especificação da API aberta:

    Campo Descrição Predefinição
    Nome Nome do proxy de API. Por exemplo: Mock-Target-API. Propriedade title da especificação OpenAPI com espaços substituídos por travessões
    Caminho base Componente do caminho que identifica de forma exclusiva este proxy de API na organização. O URL público deste proxy de API é composto pelo nome do seu domínio externo ou interno e por este caminho base. Por exemplo: http://apitest.acme.com/mock-target-api Conteúdo do campo Nome convertido para minúsculas
    Descrição Descrição do proxy de API. description da propriedade da especificação OpenAPI
    Destino (API existente) URL de destino invocado em nome deste proxy de API. Pode usar qualquer URL acessível através da Internet aberta. Por exemplo: http://mocktarget.apigee.net servers da propriedade da especificação OpenAPI

    Segue-se um excerto da especificação OpenAPI que mostra as propriedades usadas para pré-preencher os campos.

    openapi: 3.0.0
info:
  description: OpenAPI Specification for the Apigee mock target service endpoint.
  version: 1.0.0
  title: Mock Target API
paths:
  /:
    get:
      summary: View personalized greeting
      operationId: View a personalized greeting
      description: View a personalized greeting for the specified or guest user.
      parameters:
        - name: user
          in: query
          description: Your user name.
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Success
...
servers:
  - url: http://mocktarget.apigee.net
  - url: https://mocktarget.apigee.net
...
  7. Na página Detalhes do proxy, edite o campo Descrição da seguinte forma: 
    API proxy for the Apigee mock target service endpoint.
  8. Clicar em Seguinte.
  9. Na página Políticas comuns, em Segurança: autorização, certifique-se de que a opção Passagem (sem autorização) está selecionada e clique em Seguinte:

    A opção Pass through (no authorization) selecionada na página Common policies

  10. Na página Fluxos, certifique-se de que todas as operações estão selecionadas. Crie fluxos de proxy
  11. Clicar em Seguinte.
  12. Na página Resumo, certifique-se de que um ambiente está selecionado em Implementação opcional e clique em Criar e implementar:

    O Apigee cria o novo proxy de API e implementa-o no seu ambiente:

  13. Clique em Editar proxy para apresentar a página Vista geral do proxy de API.

Teste o proxy de API

Pode testar a sua API Mock-Target-API através do cURL ou de um navegador de Internet.

curl -v YOUR_ENV_GROUP_HOSTNAME/myproxy

em que YOUR_ENV_GROUP_HOSTNAME é o nome do anfitrião do grupo de ambientes. Consulte Encontre o nome do anfitrião do seu grupo de ambientes.

Por exemplo: 

curl -v -k https://apitest.acme.com/myproxy

Resposta

Deverá ver a seguinte resposta:

Hello, Guest!

Adicione uma política de XML para JSON

Em seguida, adiciona a política XML para JSON ao fluxo condicional Ver resposta XML que foi gerado automaticamente quando criou o proxy de API a partir da especificação OpenAPI. A política converte a resposta XML do destino numa resposta JSON.

Primeiro, chame a API para poder comparar os resultados com os recebidos depois de adicionar a política. Numa janela de terminal, execute o seguinte comando cURL. Está a chamar o recurso /xml do serviço de destino, que devolve nativamente um bloco simples de XML.

curl -v https://YOUR_ENV_GROUP_HOSTNAME/mock-target-api/xml

onde YOUR ENV_GROUP_HOSTNAME é o nome do anfitrião do grupo de ambientes. Consulte Encontre o nome de anfitrião do grupo de ambientes.

Resposta

Deverá ver a seguinte resposta:

<root> 
  <city>San Jose</city> 
  <firstName>John</firstName> 
  <lastName>Doe</lastName> 
  <state>CA</state> 
</root>

Agora, vamos fazer algo que converta a resposta XML em JSON. Adicione a política XML para JSON ao fluxo condicional Ver resposta XML no proxy de API.

Apigee na Cloud Console

  1. Clique no separador Develop (Desenvolver) na página Mock-Target-API Overview (Vista geral da API de destino simulada) na IU do Apigee.

    2. Selecione Ver resposta XML

  2. No painel do lado esquerdo, em Proxy Endpoints > default, clique no fluxo condicional Ver resposta XML.
  3. No painel do lado esquerdo, clique no botão + na linha Políticas.

  4. Na caixa de diálogo Criar política, clique no campo Selecionar tipo de política, desloque a página para baixo até Mediação e selecione XMLToJSON. Mantenha os valores predefinidos para Nome a apresentar e Nome.

  5. Clique em Criar para criar a política.

  6. Clique no botão + junto ao fluxo Ver resposta XML em Resposta.

    Selecione +Passo

  7. Na caixa de diálogo Adicionar passo de política, clique no campo Selecionar política existente e selecione XML para JSON-1.

  8. Clique em Adicionar. A política de XML para JSON é aplicada à resposta.

    Política de XML para JSON no fluxo

    Para ver o código do fluxo condicional Ver resposta XML, clique em Mudar para o editor de código.

  9. Clique em Guardar.

IU do Apigee Classic

  1. Clique no separador Develop (Desenvolver) na página Mock-Target-API Overview (Vista geral da API de destino simulada) na IU do Apigee.

    Separador Programador

  2. No painel de navegação do lado esquerdo, em Proxy Endpoints > default, clique no fluxo condicional Ver resposta XML.

    Selecione Ver resposta XML

  3. Clique no botão +Passo na parte inferior, correspondente à Resposta do fluxo.

    Selecione +Passo

    A caixa de diálogo Adicionar passo é aberta para apresentar uma lista categorizada de todas as políticas que pode adicionar.

  4. Desloque a página até à categoria Mediação e selecione XML para JSON.

    Caixa de diálogo Adicionar passo
  5. Mantenha os valores predefinidos para Nome a apresentar e Nome.

  6. Clique em Adicionar. A política de XML para JSON é aplicada à resposta.

    Política de XML para JSON no fluxo
  7. Clique em Guardar.

Agora que adicionou a política, chame novamente a API com o cURL. Repare que continua a chamar o mesmo recurso /xml. O serviço de destino continua a devolver o respetivo bloco de XML, mas agora a política no proxy de API converte a resposta em JSON. Faça esta chamada:

curl -v https://YOUR_ENV_GROUP_HOSTNAME/mock-target-api/xml

onde YOUR ENV_GROUP_HOSTNAME é o nome do anfitrião do grupo de ambientes. Consulte Encontre o nome de anfitrião do grupo de ambientes.

Tenha em atenção que a resposta XML é convertida em JSON:

{"root":{"city":"San Jose","firstName":"John","lastName":"Doe","state":"CA"}}