Publicar as APIs (versão original)

Esta é a documentação do Apigee Edge.
Acesse Documentação da Apigee X. informações

Publique APIs no seu portal para disponibilizá-las para consumo pelos desenvolvedores de apps, como descrito nas seções a seguir.

Visão geral da publicação da API

O processo de publicação de APIs no portal é um processo de duas etapas:

1. Selecione o produto de API que você quer publicar no portal.
2. Gere automaticamente a documentação de referência da API com base em um snapshot da especificação da OpenAPI para permitir que os desenvolvedores de apps conheçam as APIs. Para mais informações sobre snapshots, consulte O que é um snapshot de uma especificação OpenAPI?.

Quando você publica uma API no portal, as seguintes atualizações são feitas automaticamente:

• Uma página de referência da API é adicionada ao seu portal
  A página de referência da API exibe a documentação de referência da API que você gera automaticamente a partir de um snapshot da sua especificação OpenAPI. Os desenvolvedores podem conferir a documentação da API e clicar em Testar para fazer uma solicitação de API e conferir a saída.

  Observação: não é possível editar o conteúdo desta página diretamente. ele não aparecerá na lista de páginas do seu portal.

  

• Um link para a página "Referência da API" foi adicionado à página "APIs"
  A página de APIs (incluída no portal de exemplo) oferece uma lista de todas as APIs publicadas no seu portal com links para a respectiva documentação de referência da API para mais informações.

  Observação: não é possível editar o conteúdo desta página diretamente. ele não aparecerá na lista de páginas do seu portal.

  

O que é um snapshot de uma especificação OpenAPI?

Cada especificação OpenAPI serve como fonte da verdade durante todo o ciclo de vida de uma API. A mesma especificação é usada em cada fase do ciclo de vida da API, desde o desenvolvimento até a publicação e o monitoramento. Ao modificar uma especificação, é preciso compreender o impacto que as alterações têm na API por meio de outras fases do ciclo de vida, conforme descrito em O que acontece se eu modificar uma especificação?

Ao publicar a API, você faz um snapshot da especificação OpenAPI para gerar a documentação de referência da API. Esse snapshot representa uma versão específica da especificação no armazenamento de especificações. Se você modificar a especificação OpenAPI usando o editor de especificações, poderá fazer outro snapshot da especificação para refletir as alterações mais recentes na documentação de referência da API.

Como adicionar suporte ao CORS aos proxies de API

Antes de publicar suas APIs, será preciso adicionar suporte a CORS nos seus proxies de API para dar suporte a solicitações de origem cruzada do lado do cliente.

O Compartilhamento de recursos entre origens (CORS, na sigla em inglês) é um mecanismo padrão que permite que as chamadas JavaScript XMLHttpRequest (XHR) executadas em uma página da Web interajam com recursos de domínios que não são de origem. O CORS é uma solução comumente implementada na política de mesma origem que é aplicada por todos os navegadores. Por exemplo, se você fizer uma chamada XHR para a API do Twitter pelo código JavaScript em execução no navegador, a chamada falhará. Isso ocorre porque o domínio que exibe a página no seu navegador não é o mesmo que disponibiliza a API Twitter. O CORS oferece uma solução para esse problema, permitindo que os servidores "ativem" se quiserem fornecer compartilhamento de recursos entre origens.

Para informações sobre como adicionar suporte ao CORS aos proxies de API antes de publicar as APIs, consulte Como adicionar suporte ao CORS a um proxy de API.

Observação: a maioria dos navegadores mais recentes aplica o CORS. Consulte a lista completa de navegadores compatíveis. Para ver uma descrição detalhada do CORS, consulte a Recomendação do W3C de compartilhamento de recursos entre origens.

Conheça a página de APIs

Para acessar a página de APIs:

1. Selecione Publicar > Portais e selecione seu portal.
2. Clique em APIs na página inicial do portal.

Também é possível selecionar APIs no menu suspenso do portal, na barra de navegação superior.

A lista de APIs é exibida.

Como destacado na figura anterior, a página de APIs permite:

• Ver os detalhes das APIs disponíveis no seu portal
• Adicionar uma API ao portal
• Criar um snapshot da especificação da OpenAPI associada a um produto de API para atualizar a documentação de referência da API
• Publicar ou cancelar a publicação de uma API no portal
• Gerenciar o público de uma API no seu portal
• Edite a especificação associada (consulte Criar especificações usando o editor de especificações)
• Remover uma API do seu portal
• Identifique rapidamente "órfãos" APIs em que o produto de API associado foi removido do Edge e recriar o produto de API ou excluir a API do portal

Adicionar uma API ao seu portal

Observação: você pode adicionar até 100 APIs ao seu portal.

Para adicionar uma API ao portal:

1. Selecione Publicar > Portais e selecione seu portal.
2. Clique em APIs na página inicial do portal.
   Também é possível selecionar APIs no menu suspenso do portal, na barra de navegação superior.
3. Clique em + API.
   A caixa de diálogo "Add API Product to Portal" é exibida.

4. Na guia "API Product" na caixa de diálogo, selecione o produto de API que você quer adicionar ao portal.
   

5. Clique em Próxima.

6. Selecione a origem a ser usada no snapshot.
   Se você criou o proxy de API incluído no produto de API usando uma especificação OpenAPI, selecione a especificação na lista suspensa.
   

   Também é possível selecionar:

   • Nenhuma especificação e adicione uma mais tarde após a API ter sido publicada, conforme descrito em Como gerar um snapshot da especificação.
   • Escolha uma especificação diferente para selecionar ou fazer upload de uma nova especificação.

7. Marque a caixa de seleção Publicado para publicar a API no portal. Desmarque Publicado se você não quiser publicar a API.
   Você pode alterar a configuração mais tarde, conforme descrito em Como publicar ou cancelar a publicação de uma API no seu portal.

8. Em "Público", selecione uma das seguintes opções para gerenciar o público da sua API, permitindo o acesso a:

   • Usuários anônimos para permitir que todos os usuários visualizem a página.
   • Usuários registrados para permitir que apenas usuários registrados vejam a página.

   Você pode mudar a configuração mais tarde, conforme descrito em Gerenciar o público-alvo de uma API no portal.

9. Clique em Finish.

Capturar um snapshot da especificação

Depois de publicar a API, é possível fazer um novo instantâneo da especificação OpenAPI para atualizar a documentação de referência da API publicada no seu portal.

Para capturar um snapshot da especificação OpenAPI:

1. Selecione Publicar > Portais e selecione seu portal.
2. Clique em APIs na página inicial do portal.
   Também é possível selecionar APIs no menu suspenso do portal, na barra de navegação superior.
3. Posicione o cursor sobre a API para a qual você quer capturar um snapshot para exibir as ações.

4. Clique em .

   Observação: uma mensagem será exibida se o snapshot estiver com a especificação de origem selecionada.

5. Selecione uma especificação existente na lista suspensa "Origem do snapshot" ou escolha Escolher uma especificação diferente para selecionar ou fazer upload de uma nova especificação a ser usada na geração da documentação da API. Como alternativa, selecione Nenhuma especificação para remover a especificação atual.

6. Clique em Atualizar snapshot (ou Remover snapshot se você tiver selecionado "Nenhuma especificação").

A documentação de referência da API é gerada com base na especificação e adicionada à página "Referência da API".

Publicar ou cancelar a publicação de uma API no seu portal

Para publicar ou cancelar publicação de uma API no portal:

1. Selecione Publicar > Portais e selecione seu portal.
2. Clique em APIs na página inicial do portal.
   Também é possível selecionar APIs no menu suspenso do portal, na barra de navegação superior.
3. Posicione o cursor sobre a API que você quer publicar ou cancelar a publicação.
4. Clique em .
5. Marque a caixa de seleção Ativar para publicar a API no portal. Desmarque Ativar para cancelar a publicação da API.
6. Clique em Salvar.

Gerenciar o público de uma API no seu portal

Gerencie o público-alvo da API no seu portal permitindo o acesso a:

• Todos os usuários
• Somente usuários registrados

Para gerenciar o público de uma API no seu portal:

1. Selecione Publicar > Portais e selecione seu portal.
2. Clique em APIs na página inicial do portal.
   Também é possível selecionar APIs no menu suspenso do portal, na barra de navegação superior.
3. Posicione o cursor sobre a API de que você quer gerenciar o público para exibir as ações.
4. Clique em .
5. Em "Público", selecione uma das seguintes opções:
   • Usuários anônimos para permitir que todos os usuários vejam o produto da API.
   • Usuários registrados para permitir que apenas usuários registrados vejam o produto de API.
6. Clique em Salvar.

Remover uma API do seu portal

Para remover uma API do seu portal:

1. Selecione Publicar > Portais e selecione seu portal.
2. Clique em APIs na página inicial do portal.
   Também é possível selecionar APIs no menu suspenso do portal, na barra de navegação superior.
3. Posicione o cursor sobre a API na lista para exibir o menu de ações.
4. Clique em .

Resolver problemas com as APIs publicadas

Ao usar o recurso "Testar", se o erro TypeError: Failed to fetch for retornado, considere as seguintes causas e resoluções possíveis:

• Para erros de conteúdo misto, o erro pode ser causado por um problema known swagger-ui. Uma alternativa possível é especificar o HTTPS antes do HTTP na definição de schemes na especificação OpenAPI. Exemplo:

   schemes:
     - https
     - http
  

• Para erros de restrição do CORS (Compartilhamento de recursos entre origens), verifique se o CORS é compatível com seus proxies de API. O CORS é um mecanismo padrão que permite solicitações entre origens do cliente. Consulte Adicionar suporte ao CORS em um proxy de API. Verifique se o CORS também está ativado no navegador.