Como usar o SmartDocs para documentar APIs

Você está vendo a documentação do Apigee Edge.
Acesse a documentação da Apigee X.
informações

O SmartDocs permite documentar suas APIs no portal do desenvolvedor do Drupal 7 de uma maneira que torne a documentação da API totalmente interativa. Com a documentação interativa, os usuários do portal podem:

  • Leia sobre suas APIs
  • Enviar uma solicitação em tempo real para a API
  • Veja uma resposta em tempo real retornada da API

Ao criar uma documentação interativa sobre suas APIs, o usuário do portal pode aprender, testar e avaliar suas APIs com mais facilidade.

A API Edge Management é uma API RESTful que permite acessar os serviços da API usando qualquer cliente HTTP. A Apigee usa o SmartDocs para criar documentação interativa da API Edge Management. Consulte a documentação da API.

Exemplo do portal SmartDocs

Para usar o SmartDocs, você precisa ter um portal de serviços para desenvolvedores da Apigee. Para mais informações, consulte Como criar um portal do desenvolvedor.

Na página inicial do portal do desenvolvedor, clique em APIs na barra de navegação superior para ver a página de documentação da API.

Há duas APIs documentadas no portal: Hello World e Exemplo da Pet Store.

A API Hello World foi criada a partir da especificação OpenAPI de destino simulada, mocktarget.yaml. Para mais informações, consulte https://github.com/apigee/api-platform-samples/tree/master/default-proxies/helloworld/openapi.

A API de exemplo da Pet Store foi criada com base na demonstração clássica do pet shop.

Conheça a API Hello World:

  1. Clique em API Hello World. A página de resumo da API Hello World será exibida:
  2. Clique em Ver afirmação da API. Os SmartDocs deste recurso são exibidos:
  3. Clique em Enviar esta solicitação.
  4. Veja a resposta retornada:
    HTTP/1.1 200 OK
    Connection:
    keep-alive
    Content-Length:
    18
    Content-Type:
    text/html; charset=utf-8
    Date:
    Tue, 21 Jun 2016 21:49:32 GMT
    ETag:
    W/"12-Jb9QP1bUxNSmZkxQGt5KLQ"
    X-Powered-By:
    Apigee
    <H2>I <3 APIs</H2>
    
  5. Clique na guia Solicitação para ver a solicitação ou na guia cURL para ver a chamada de cURL correspondente.

Como documentar suas APIs usando SmartDocs

O SmartDocs representa suas APIs usando um model, em que o modelo contém todas as informações sobre suas APIs. O portal extrai informações sobre suas APIs do modelo para renderizar as páginas de documentação no portal como nós do Drupal, em que cada nó do Drupal corresponde a uma página de documentação no portal.

As etapas gerais para usar o SmartDocs são:

  1. Configure o módulo SmartDocs do Drupal no portal.
  2. Crie um modelo do SmartDocs.
  3. Adicione APIs ao modelo a partir de um arquivo WADL, especificação OpenAPI (antigo Swagger) ou manualmente.
  4. Renderize o modelo como uma coleção de nós do Drupal. Cada nó do Drupal contém informações sobre uma única API. Por exemplo, se um recurso na sua API for compatível com solicitações POST e PUT, o SmartDocs criará um nó Drupal separado para POST e PUT.
  5. Publique os nós do Drupal. Depois de publicados, os usuários do portal poderão visualizar e interagir com sua API.
  6. Edite os nós do Drupal antes ou depois de publicá-los. É possível editar os nós do Drupal usando o editor do Drupal ou o arquivo WADL original ou a especificação OpenAPI. Quando terminar de editar o arquivo WADL ou a especificação OpenAPI, importe-o de volta para o modelo como uma nova revisão. Em seguida, renderize e publique suas alterações.
  7. Ative o TLS. Como o SmartDocs pode enviar credenciais de autenticação para o back-end como parte do processo de solicitação às APIs, ative o TLS no portal para garantir que essas credenciais estejam seguras. Nos ambientes de produção e teste do portal, a Apigee fornece o certificado TLS necessário para fazer solicitações https://. No entanto, antes de ativar seu portal, é necessário receber seu próprio certificado TLS e ativar o TLS. Para mais informações, consulte Como usar o TLS no portal.

Sobre modelos e modelos do SmartDoc

Quando você cria um modelo no portal, o modelo é armazenado na sua organização do Edge, não no Drupal. Um modelo é um grande bloco de JSON com um nome interno (como "my-smartdocs-api") e define a estrutura de uma API. O portal, por outro lado, renderiza o modelo em HTML e fornece uma interface de edição para o modelo. Todas as atualizações da API no portal são automaticamente enviadas de volta ao modelo de origem.

Armazenado na organização

Armazenado no Drupal

ajustáveis

templates

Nós do Drupal com funcionalidade de edição

Suponha que você tenha vários portais na sua organização (por exemplo, desenvolvimento, estágio e produção). No Pantheon, você move um portal de um ambiente para outro. Cada instância do portal tem um modelo próprio, mas todas elas estão realmente se referindo ao modelo de origem. Se você editar a API em dev, o modelo será atualizado e as alterações aparecerão na produção. Da mesma forma, se você excluir um modelo em dev, a origem será excluída e não estará mais disponível na produção.

Os modelos controlam a aparência dos seus SmartDocs, e esses modelos (controlados por Handlebars e arquivos CSS) são armazenados com cada instância do portal. Teoricamente, cada portal pode usar um modelo exclusivo para cada modelo. No entanto, uma das conveniências do framework de renderização é que um modelo padrão (seja o padrão da Apigee ou um modelo fornecido por você) é aplicado automaticamente a cada modelo.

O diagrama a seguir mostra a relação entre modelos e portais. As setas verdes mostram a sincronização automática.

O comando cURL a seguir lista todos os modelos na sua organização:

curl -v https://api.enterprise.apigee.com/v1/o/{your_org}/apimodels/ -u edge_org_admin@example.com

Como configurar o módulo SmartDocs

A Apigee implementou o SmartDocs como um módulo personalizado do Drupal. Use o procedimento a seguir para configurar o módulo SmartDocs.

Para configurar o módulo SmartDocs:

  1. Faça login no portal como usuário com privilégios de administrador ou de criação de conteúdo.
  2. Selecione Modules no menu de administração do Drupal. A lista de todos os módulos Drupal instalados será exibida.
  3. Ative o módulo SmartDocs.
  4. Salve a configuração.
  5. Selecione Modules no menu de administração do Drupal.
  6. Selecione SmartDocs -> Permissões e verifique se a opção "Executar tarefas de administração para o módulo SmartDocs" para o papel "Administrador" está ativada.
  7. Selecione Configuration > Dev Portal no menu de administração do Drupal.
  8. Defina Tempo limite de conexão e Tempo limite da solicitação como 16 segundos.
  9. Salve a configuração.
  10. Defina as configurações de URL:
    1. Selecione Configuration > Search and metadata > URL aliases > Settings no menu do Drupal.
    2. Defina o Comprimento máximo do alias e o Comprimento máximo do componente como 255.
    3. Expanda Pontuação.
    4. Nas configurações de Chave esquerda ({) e Chave direita (}), selecione Nenhuma ação (não substituir).
    5. Clique em Salvar configuração.
  11. Se o portal do desenvolvedor for exposto a usuários em uma rede interna sem acesso à Internet ou se um subconjunto das APIs estiver em uma rede privada, configure o URL do proxy da API SmartDocs da seguinte maneira:
    1. Selecione Configuration > SmartDocs no menu do Drupal Administration.
    2. Expanda Configurações avançadas.
    3. Atualize o campo URL do proxy do SmartDocs da seguinte maneira: <host>/smartdocs/v1/sendrequest.
      A ajuda inline precisa fornecer o valor necessário para seu ambiente. Por exemplo:
      https://api-us-east-1-enterprise.apigee.com/smartdocs/v1/sendrequest

      O padrão deste campo é https://apiconsole-prod.apigee.net/smartdocs/v1/sendrequest.
    4. Clique em Salvar configuração.

Como criar um modelo

Um modelo contém todas as informações sobre a representação da sua API. É possível definir vários modelos no portal para oferecer suporte a diferentes APIs ou agrupar todas as suas APIs em um único modelo.

Cada modelo especifica um nome interno exclusivo que também define o URL de base dos nós Drupal gerados. O URL de cada nó Drupal está no formato:

http://<drupalBasePath>/<internalName>/apis/<httpMethod>/<resourcePath>

onde:

  • drupalBasePath: o URL de base do seu portal.
  • internalName: o nome interno do modelo.
  • httpMethod: o método HTTP da API, como: get, put, post ou delete.
  • resourcePath: o caminho do recurso.

Por exemplo, se você especificar o nome interno como "mymodel", o URL do nó Drupal gerado para uma solicitação GET para um recurso chamado "/books" será:

http://prod-myco.devportal.apigee.com/mymodel/apis/get/books

Para criar um modelo

Quando você cria um modelo, ele é armazenado na sua organização do Edge como origem da estrutura da API. Para mais informações, consulte Sobre modelos e modelos do SmartDoc.

  1. Faça login no portal como usuário com privilégios de administrador ou de criação de conteúdo.
  2. Selecione Content > SmartDocs no menu de administração do Drupal.
  3. Selecione Novo modelo na parte de cima da página.
  4. Preencha os seguintes campos:
    • Nome: é o nome do modelo que será exibido em todo o site.
    • Nome interno: conforme você digita o Nome, o nome interno é exibido. O nome interno do modelo que precisa ser único entre todos os modelos. O nome interno precisa ter somente letras minúsculas, números e hifens sem espaços. Selecione Editar para editar o nome.
    • Descrição: uma descrição do modelo.
  5. Selecione Criar modelo.

Depois de criar o modelo, a página dele será aberta. A partir daí, é possível usar o menu suspenso "Operações" bx para:

  • Importe um arquivo WADL que descreva sua API ou especifique o URL de uma especificação OpenAPI que descreva sua API.
  • Adicionar revisão ao modelo
  • Modifique as Configurações do modelo, inclusive as folhas de estilo usadas por ele.
  • Exporte o modelo para um arquivo.
  • Exclua o modelo.

Como adicionar APIs a um modelo

É possível adicionar APIs a um modelo:

  • Como importar um arquivo WADL contendo a definição da API
  • Como importar uma especificação OpenAPI (OpenAPI 2.0 ou 1.2)
  • Criação manual de recursos e métodos

Você também pode importar um arquivo JSON do SmartDocs para um modelo. Esse arquivo normalmente é criado ao exportar um modelo atual, editar o arquivo e, em seguida, importar as atualizações. Para mais informações, consulte "Como exportar e importar um modelo" abaixo.

Vídeo: assista a um vídeo curto para saber como adicionar APIs a um modelo SmartDocs por meio da importação de uma especificação OpenAPI.

Importar uma WADL

Depois de criar um modelo, importe um arquivo WADL que descreva sua API. Sempre que você importa um arquivo WADL, cria automaticamente uma nova revisão do modelo.

  1. Faça login no portal como usuário com privilégios de administrador ou de criação de conteúdo.
  2. Selecione Content > SmartDocs no menu de administração do Drupal.
  3. Selecione o modelo que você quer atualizar.
  4. Em Operações, selecione Importar.
  5. Selecione WADL no menu suspenso Escolher formato na página de importação do SmartDocs.
  6. Selecione File ou URL na lista suspensa Upload Type.
    1. Se você selecionar Arquivo, procure o arquivo WADL.
    2. Se você selecionar URL, especifique o URL do arquivo WADL.
  7. Clique em Importar para importar para o modelo. Agora é possível renderizar o modelo.
  8. Você será redirecionado para a página de informações do modelo, onde é possível renderizá-lo.

Importar uma especificação OpenAPI

Depois de criar um modelo, é possível importar uma especificação OpenAPI (antigo Swagger). O Edge oferece suporte às versões 1.2 e 2.0 da OpenAPI.

A OpenAPI usa arquivos que contêm objetos JSON para descrever uma API. Sempre que você importa uma especificação OpenAPI, cria automaticamente uma nova revisão do modelo.

Para importar uma especificação OpenAPI:

  1. Faça login no portal como usuário com privilégios de administrador ou de criação de conteúdo.
  2. Selecione Conteúdo > SmartDocs no menu de administração do Drupal.
  3. Selecione o modelo que você quer atualizar.
  4. Em Operações, selecione Importar.
  5. Selecione JSON Swagger ou YAML do Swagger no menu suspenso Escolher formato da página de importação do SmartDocs.
  6. Selecione Arquivo ou URL na lista suspensa Tipo de upload. É necessário selecionar URL para a OpenAPI 1.2.
    1. Se você selecionar File, navegue até a especificação OpenAPI.
    2. Se você selecionar URL, especifique o URL da especificação OpenAPI.
  7. Clique em Importar para importar para o modelo.
  8. Você será redirecionado para a página de informações do modelo, onde é possível renderizá-lo.

Criar recursos e métodos manualmente

Se você não tiver um arquivo WADL ou uma especificação OpenAPI que represente sua API, poderá adicionar APIs manualmente ao modelo. Além disso, se você usar um arquivo WADL ou uma especificação OpenAPI para criar seu modelo, poderá usar este procedimento para editar suas APIs, incluindo a adição de novas APIs, após a importação.

Para adicionar uma API manualmente:

  1. Crie uma nova revisão do modelo.

    Ao criar a revisão, você especifica o único caminho base de todas as APIs no modelo, o que significa que todas as APIs em um modelo compartilham o mesmo caminho base. Por exemplo, especifique o caminho base como:

    https://myCompany.com/v1

    Quando você adiciona recursos ao modelo, eles estendem o caminho base.
  2. Defina um ou mais recursos para o modelo. O caminho do recurso é combinado com o caminho base da revisão do modelo para especificar o URL completo do recurso. Por exemplo, se o recurso definir um caminho "/login", o URL completo do recurso será:

    https://myCompany.com/v1/login
  3. Defina um ou mais métodos para cada recurso. Um método especifica o verbo HTTP que pode ser invocado em um recurso. Por exemplo, para o recurso "/login", você oferece suporte a POST para login e DELETE para logout. Este recurso não aceita outros verbos HTTP, como PUT ou GET. Portanto, defina dois métodos para o recurso, um para POST e outro para DELETE.

    O método usa o URL do recurso pai. Portanto, todos os métodos com o mesmo URL são definidos em um único recurso em SmartDocs.

Como regra geral:

  • Crie um modelo SmartDocs diferente para cada caminho base exclusivo na API.
  • Defina um recurso SmartDocs diferente para cada recurso exclusivo da API.
  • Defina um método SmartDocs diferente para cada verbo HTTP compatível com um recurso.

Como criar uma nova revisão de um modelo

Só é possível adicionar um recurso a uma revisão atual de um modelo. Se o modelo já tiver uma revisão, adicione o recurso. Se o modelo for novo e não tiver revisões, crie uma nova revisão.

Para criar uma revisão de um modelo:

  1. Faça login no portal como usuário com privilégios de administrador ou de criação de conteúdo.
  2. Selecione Conteúdo > SmartDocs no menu de administração do Drupal.
  3. No modelo que você quer atualizar, selecione Adicionar revisão em Operações.
  4. Na página Adicionar revisão da API, insira as seguintes informações:
    • Nome de exibição: o nome da revisão como aparece no portal.
    • ID da versão: um identificador curto para a revisão.
    • Descrição: uma descrição da revisão.
    • URL de base: o URL de base de todas as APIs na revisão do modelo. Um modelo pode usar URLs de base diferentes para cada revisão. Por exemplo, você inclui um indicador de versão no URL base. Para a primeira revisão do modelo, o URL base é:
      https://myCompany.com/v1
      Para a próxima revisão, o URL base pode ser:
      https://myCompany.com/v2
  5. Selecione Adicionar revisão. Você será redirecionado para a página de revisão do modelo. Agora é possível definir recursos no modelo.

Como definir um recurso

Um recurso especifica o URL completo de uma API. Ao definir um recurso, você especifica o caminho do recurso, que é combinado com o URL de base na revisão do modelo para criar o URL completo do recurso.

Para definir um recurso:

  1. Faça login no portal como usuário com privilégios de administrador ou de criação de conteúdo.
  2. Selecione Conteúdo > SmartDocs no menu de administração do Drupal.
  3. No modelo que você quer atualizar, em Operações, selecione Revisões de API para ver todas as revisões de um modelo.
  4. Selecione uma revisão para editar.
  5. Na página de revisão, selecione Add Resource no menu suspenso.
  6. Na página Adicionar recurso, digite as seguintes informações:
    • Nome de exibição: o nome do recurso.
    • Caminho: o caminho do recurso, começando com "/". O valor de Path é combinado com o URL de base da revisão do modelo para criar o URL completo do recurso.
    • Descrição: uma descrição do recurso.
    • Parâmetros: se quiser, insira o objeto JSON que define cada parâmetro no recurso. Esses parâmetros são descritos abaixo.
  7. Selecione Adicionar recurso. Você será redirecionado para a página do modelo. Agora é possível definir métodos no recurso.

Opcionalmente, adicione parâmetros ao recurso, como modelo, consulta e cabeçalho. Todos os parâmetros do recurso são herdados por qualquer método definido nesse recurso. Portanto, se você definir um parâmetro de consulta no recurso, todos os métodos adicionados a esse recurso precisarão ser compatíveis com esse parâmetro.

Como alternativa, você pode definir parâmetros em um método. Por exemplo, um método POST pode aceitar parâmetros de consulta que não são aceitos por um método DELETE. Portanto, adicione parâmetros específicos a um método ao defini-lo, conforme descrito abaixo.

A imagem a seguir mostra uma página SmartDocs existente para a API Apigee Aprovar ou Revogar app do desenvolvedor com cada tipo de parâmetro em destaque:

Cada tipo de parâmetro é definido por um objeto JSON:

Tipo

objeto JSON

Observações

Modelo

{
"dataType": "string",
"defaultValue": "",
"description": "O nome da organização.",
"name": "org_name",
"required": true,
"type": "TEMPLATE"
}

Os parâmetros do modelo são sempre obrigatórios. Portanto, defina required como true e omita o valor como defaultValue.

O valor da description aparece em um pop-up quando o usuário passa o cursor sobre o URL em uma página do SmartDocs.

Consulta

{
"dataType": "string",
"defaultValue": "",
"description": "O local.",
"name": "w",
"required": true,
"type": "QUERY"
}

Os parâmetros de consulta obrigatórios ainda podem especificar um defaultValue, mas isso geralmente não acontece.

Para parâmetros de consulta opcionais, defina required como false e especifique um valor para defaultValue.

Cabeçalho

{
"dataType": "string",
"defaultValue": "application/json",
"description": "Especifique como <code>application/json</code>.",
"name": "Content-Type",
"required": true,
"type": "HEADER"
}

Observe como você pode usar tags HTML na descrição.

Um parâmetro do modelo define uma variável no caminho do recurso. Por exemplo, você define dois parâmetros de modelo no recurso. Observe como cada definição de parâmetro na matriz de parâmetro é separada por uma vírgula:

[
 {
  "dataType": "string",
  "defaultValue": "",
  "description": "Mention the organization name.",
  "name": "org_name",
  "required": true,
  "type": "TEMPLATE"
 },
 {
  "dataType": "string",
  "defaultValue": "",
  "description": "Mention the user email.",
  "name": "developer_email",
  "required": true,
  "type": "TEMPLATE"
 }
]

Em seguida, você pode usar os parâmetros do modelo na definição do caminho do recurso, incluídos em "{}". Por exemplo, defina o caminho como:

/login/{org_name}/{developer_email}

Na página da API SmartDocs, o usuário precisa editar o URL para especificar as partes org_name e developer_email do URL antes de enviar uma solicitação.

Como definir um método

Defina um ou mais métodos para cada recurso. A definição do método especifica um verbo HTTP que pode ser invocado no recurso. Um recurso pode ter um único método definido ou vários métodos.

Como parte da definição do método, especifique todos os parâmetros usados por ele, incluindo parâmetros de consulta e cabeçalho. Consulte a descrição acima para conferir informações sobre como adicionar parâmetros a um método.

A imagem a seguir mostra uma página SmartDocs atual da API Create Developer da Apigee, com cada área da página destacada com o valor correspondente definido na definição de um método:

A próxima imagem mostra a mesma página, mas com a descrição do corpo da solicitação selecionada:

Para definir um método:

  1. Faça login no portal como usuário com privilégios de administrador ou de criação de conteúdo.
  2. Selecione Conteúdo > SmartDocs no menu de administração do Drupal.
  3. No modelo que você quer atualizar, em Operações, selecione Revisões de API para ver todas as revisões de um modelo.
  4. Selecione uma revisão para editar.
  5. Na página de revisão, selecione Adicionar método no menu suspenso de um dos recursos.
  6. Na página Editar método, digite as seguintes informações:
    • Nome de exibição: o nome da API, que também se torna o título da página do Drupal da API.
    • Descrição: descreva a API.
    • Método Verbo: o tipo de verbo HTTP.
    • Esquemas de segurança: especifique o modo de autenticação, se houver, para o método. Para mais informações, consulte Como configurar o tipo de autenticação SmartDocs.
    • Tipo de conteúdo: o tipo de conteúdo da solicitação e da resposta. Consulte a seção abaixo sobre como configurar diferentes métodos de autenticação.
    • Parâmetros: (opcional) todos os parâmetros de consulta ou cabeçalho para o método. Consulte a descrição acima para saber mais sobre como adicionar um parâmetro a um recurso.
    • Documentação do corpo da solicitação (opcional): descreva o corpo da solicitação. Os métodos POST e PUT recebem um corpo de solicitação. Você pode usar essa área para descrevê-la. Se você omitir esse valor, o link Descrição em Corpo da solicitação será omitido da página SmartDocs gerada.
    • Exemplo de corpo de solicitação (opcional): mostre um exemplo de corpo de solicitação, normalmente como um objeto JSON ou como um XML. Para os verbos POST e PUT, o exemplo de corpo da solicitação é transmitido como parte de cada solicitação. Os usuários da página SmartDocs editam este exemplo antes de enviar uma solicitação à API. Se você omitir esse valor, o link Valor em Corpo da solicitação será omitido da página SmartDocs gerada.
    • Tags: matriz de tags associadas à API. O SmartDocs usa tags para agrupar APIs semelhantes. Por exemplo, você pode aplicar a tag "Estatísticas" a todas as APIs sobre estatísticas. Você pode agrupar APIs de recursos diferentes em uma única tag, desde que todas usem a mesma tag.
  7. Selecione Adicionar método. Você será redirecionado para a página do modelo. Agora é possível renderizar e publicar seu método.

Renderizar um modelo

Depois de adicionar APIs a um modelo, ele pode ser renderizado. A renderização converte a descrição da API do modelo em nós do Drupal. Quando a renderização for concluída, você terá um único nó Drupal para cada API, em que cada nó corresponde a uma página HTML.

Você pode renderizar o modelo inteiro de uma vez ou selecionar APIs individuais para renderização.

Para renderizar um modelo:

  1. Faça login no portal como usuário com privilégios de administrador ou de criação de conteúdo.
  2. Selecione Conteúdo > SmartDocs no menu de administração do Drupal.
  3. No modelo que você quer renderizar, selecione Revisões da API em Operações.
  4. Selecione a revisão que você quer renderizar. Só é possível renderizar nós de uma única revisão do modelo.
  5. Selecione os métodos para renderizar.
  6. Selecione Nós de renderização na lista suspensa Opções de atualização.
  7. Clique em Atualizar.
  8. Uma tela de carregamento é exibida para exibir o progresso nos nós sendo renderizados.
    Depois que os nós forem renderizados, o ID do nó Drupal de cada API vai aparecer na coluna Associação de nós do modelo. Clique no link na coluna Associação de nós para ver o nó renderizado.

Em vez de selecionar Nós de renderização,você pode selecionar Renderizar e publicar nós para renderizar e publicar imediatamente as APIs como um nó do Drupal.

Nós de publicação

Um nó não fica visível para os usuários do portal até que seja publicado. Opcionalmente, é possível publicar nós durante o processo de renderização. Se você optar por não publicar os nós, será necessário fazer isso manualmente após a conclusão da renderização.

Para publicar um nó:

  1. Faça login no portal como usuário com privilégios de administrador ou de criação de conteúdo.
  2. Selecione Conteúdo > SmartDocs no menu de administração do Drupal.
  3. No modelo que você quer publicar, selecione Revisões da API em Operações.
  4. Selecione a revisão que você quer publicar. Só é possível publicar nós de uma única revisão do modelo.
  5. Selecione os métodos para publicar.
  6. Selecione os nós na revisão para publicar.
  7. Selecione Publicar nós na lista suspensa Opções de atualização.
  8. Clique em Atualizar.
  9. Navegue até o nó selecionando o ID dele na coluna Associação de nós.

Por padrão, o URL do Drupal para um nó da API publicado tem o formato: http://<drupalBasePath>/<internalName>/apis/<httpMethod>/<resourcePath>. Use o procedimento a seguir para controlar a forma do URL:

  1. Faça login no portal como usuário com privilégios de administrador ou de criação de conteúdo.
  2. Selecione Configuration > Search and metadata > URL aliases > Patterns no menu de administração do Drupal.
  3. Em Padrão de todos os caminhos do método SmartDocs, especifique como você quer gerar o caminho.
  4. Selecione Salvar configuração.

Devido ao armazenamento em cache no portal, talvez as páginas de modelo não apareçam imediatamente após a publicação. Se necessário, limpe manualmente o cache HTML do SmartDocs usando o seguinte procedimento:

  1. Faça login no portal como usuário com privilégios de administrador ou de criação de conteúdo.
  2. Selecione Configuration > SmartDocs no menu de administração do Drupal.
  3. Clique em Recriar caches de modelo do SmartDocs.

Como cancelar a publicação de um nó

É possível cancelar a publicação de um nó publicado a qualquer momento. Cancelar a publicação de um nó o torna invisível para os usuários do portal.

Para cancelar a publicação de um nó:

  1. Faça login no portal como usuário com privilégios de administrador ou de criação de conteúdo.
  2. Selecione Content > SmartDocs no menu de administração do Drupal.
  3. No modelo que você quer cancelar a publicação, selecione Revisões da API em Operações.
  4. Selecione a revisão de modelo do nó que você quer cancelar a publicação.
  5. Selecione os nós na revisão para cancelar a publicação.
  6. Selecione a opção Cancelar publicação na lista suspensa Opções de atualização.
  7. Clique em Atualizar.

Como visualizar a revisão de um modelo

Você cria uma nova revisão de um modelo importando um novo arquivo WADL ou especificação OpenAPI para um modelo existente ou criando manualmente uma nova revisão. Depois de criar a nova revisão, é possível renderizar e publicar a revisão, que substitui os nós do Drupal publicados atualmente.

É possível renderizar e publicar nós de várias revisões ao mesmo tempo. Ou seja, se você tem cinco revisões de um modelo, é possível publicar nós de qualquer uma ou de todas elas. No entanto, ao publicar uma API em um modelo igual a um nó publicado de outro modelo, a versão anterior da API é cancelada e ela é substituída pela da API publicada mais recentemente.

Para ver a revisão de um modelo:

  1. Faça login no portal como usuário com privilégios de administrador ou de criação de conteúdo.
  2. Selecione Conteúdo > SmartDocs no menu de administração do Drupal.
  3. No modelo que você quer atualizar, selecione Revisões da API em Operações.
  4. Selecione a revisão do modelo que você quer visualizar.
  5. Renderize e publique os nós conforme descrito acima.

Como editar um nó

Depois de renderizar um nó, você pode editá-lo usando o editor do Drupal. Por exemplo, é possível editar o verbo HTTP e a descrição de uma API ou adicionar um novo parâmetro de consulta ou cabeçalho à API. É possível editar os nós criados com base em um arquivo WADL ou na especificação OpenAPI ou os nós criados manualmente.

Também é possível editar o arquivo WADL ou a especificação OpenAPI original. Quando terminar de editar, importe o arquivo WADL ou a especificação OpenAPI de volta para o modelo como uma nova revisão. Em seguida, renderize e publique suas alterações conforme descrito acima.

Para editar um nó usando o editor do Drupal:

  1. Faça login no portal como usuário com privilégios de administrador ou de criação de conteúdo.
  2. Navegue até o nó do Drupal correspondente à documentação da API que você quer editar.
  3. Selecione Edit para usar o editor do Drupal.
  4. Depois de concluir as edições, selecione Atualizar método.

Como alternativa, é possível editar o nó do modelo SmartDocs:

  1. Faça login no portal como usuário com privilégios de administrador ou de criação de conteúdo.
  2. Selecione Conteúdo > SmartDocs no menu de administração do Drupal.
  3. No modelo que você quer atualizar, selecione Revisões da API em Operações.
  4. Selecione a revisão do modelo que você quer publicar.
  5. Selecione Editar método na lista suspensa Operações para o método que você quer editar.

Para excluir um nó:

  1. Faça login no portal como usuário com privilégios de administrador ou de criação de conteúdo.
  2. Selecione Conteúdo > SmartDocs no menu de administração do Drupal.
  3. No modelo que você quer atualizar, selecione Revisões da API em Operações.
  4. Selecione a revisão do modelo que você quer publicar.
  5. Selecione Excluir método na lista suspensa Operações do método.
    Cuidado:a exclusão do nó também remove a API do modelo. Se você quiser cancelar a publicação da API apenas para que ela fique oculta dos usuários do portal, mas não queira excluí-la do modelo, cancele a publicação do nó conforme descrito acima.

O portal tem um relatório integrado que exibe informações sobre qualquer nó renderizado por um modelo SmartDocs que não se refira mais a métodos válidos do modelo. Para acessar o relatório, selecione Relatórios no menu Drupal e escolha o relatório chamado Status do nó SmartDocs.

Como exportar e importar um modelo

Com o SmartDocs, é possível exportar um modelo para um arquivo. Por exemplo, é possível definir um ambiente de produção e um de preparação. Em seguida, faça todas as edições do SmartDocs no ambiente de preparação. Quando estiver tudo pronto para lançar suas APIs, exporte o modelo de preparo e importe-o para o modelo de produção.

A importação de um modelo cria uma nova revisão do modelo. O SmartDocs tenta corresponder as APIs existentes no modelo com as APIs importadas. Se o SmartDocs detectar uma correspondência, a importação atualizará o nó Drupal correspondente à API existente. Se o SmartDocs não detectar uma correspondência, a importação criará um novo nó Drupal para a API.

Por exemplo, você tem uma API POST que corresponde a um nó Drupal com um ID 91. Em seguida, você importa um modelo, e o SmartDocs detecta uma correspondência de uma API POST no modelo importado com a API POST atual. Qualquer atualização na API POST atualiza o nó 91 do Drupal. Se o SmartDocs não detectar uma correspondência, ele criará um novo nó Drupal com um novo ID.

O Drupal executa a correspondência usando as seguintes características da API:

  • internalName: o nome do modelo interno.
  • httpMethod: o método HTTP da API, como GET, PUT, POST ou DELETE.
  • resourcePath: o caminho do recurso.
  • parâmetros de consulta: qualquer parâmetro de consulta usado pela API.

Se as quatro características de uma API importada corresponderem a uma API atual no modelo, o SmartDocs atualizará o nó atual do Drupal.

O modelo exportado é representado por um único objeto JSON com entradas para recursos e métodos. Isso significa que é possível editar o modelo exportado para modificar um recurso ou método e importá-lo novamente. Se você editar o objeto JSON, não modifique os seguintes campos:

  • revisionNumber
  • createdTime
  • modifiedTime
  • apiRevisionId
  • resourceId

Para exportar um modelo:

  1. Faça login no portal como usuário com privilégios de administrador ou de criação de conteúdo.
  2. Selecione Conteúdo > SmartDocs no menu de administração do Drupal.
  3. No modelo que você quer exportar, selecione Exportar em Operações.
  4. Selecione o tipo de arquivo de exportação como SmartDocs JSON.
  5. Clique em Exportar.
  6. Você precisa salvar o arquivo em disco ou abri-lo em um editor.

Para importar um modelo:

  1. Faça login no portal como usuário com privilégios de administrador ou de criação de conteúdo.
  2. Selecione Conteúdo > SmartDocs no menu de administração do Drupal.
  3. No modelo que você quer importar, selecione Importar em Operações.
  4. Selecione JSON do SmartDocs no menu suspenso Escolher formato.
  5. Selecione File ou URL no Tipo de upload:
    1. Se você selecionar File, navegue até o arquivo JSON.
    2. Se você selecionar URL, especifique o URL do arquivo JSON do SmartDocs.
  6. Clique em Importar para importar para o modelo.
  7. Você será redirecionado para a página de informações do modelo, onde é possível renderizá-lo. Observe que a importação cria uma nova revisão do modelo.
  8. Renderize e publique os nós.

Como editar o modelo do SmartDocs

O modelo SmartDocs define como os nós do Drupal aparecem na tela. Cada modelo do SmartDocs pode usar o mesmo modelo padrão, ou você pode personalizar manualmente o modelo usado para um modelo individual.

O modelo SmartDocs inclui um arquivo de modelo codificado como um arquivo .hbr do Handlebars, além de arquivos CSS e JavaScript. Com o Guidbars, grande parte do conteúdo é orientada por variáveis usando expressões de Handlebars incorporadas, como &123;&123;body}}. Uma lista das expressões existentes do Handlebar é fornecida em um comentário na parte de cima do arquivo. Para saber mais sobre como usar o Handlebars para personalizar seus modelos, consulte http://handlebarsjs.com.

As seções a seguir descrevem como fazer o upload de um arquivo de modelo personalizado do SmartDocs para uso de todos os novos modelos ou para quando você estiver importando novas APIs para um modelo existente, como restaurar o arquivo de modelo padrão original do SmartDocs e como modificar o modelo do SmartDocs para um modelo individual.

Fazer upload de um arquivo de modelo personalizado do SmartDocs

É possível fazer upload de um arquivo de modelo personalizado do SmartDocs como um arquivo .hbr do Handlebars para usar como modelo padrão ao criar novos modelos ou importar novas APIs para um modelo atual.

Se você quiser usar o arquivo de modelo padrão do SmartDocs como ponto de partida ao criar seu arquivo personalizado, faça o download de uma cópia em: profiles/apigee/modules/custom/devconnect/smartdocs/templates/smartdocs.hbr

Para fazer upload de um arquivo de modelo personalizado do SmartDocs:

  1. Faça login no portal como usuário com privilégios de administrador ou de criação de conteúdo.
  2. Selecione Configuration > SmartDocs no menu de administração do Drupal.
  3. Expanda a área Configurações avançadas da página.
  4. Em "Fazer upload do modelo de método personalizado", clique em Escolher arquivo e navegue até o arquivo .hbr do Handlebars.
  5. Clique em Fazer upload.
  6. Clique em Salvar configuração.

Como restaurar o arquivo de modelo padrão do SmartDocs

É possível restaurar o arquivo de modelo padrão do SmartDocs. Depois de restaurado, o arquivo de modelo padrão do SmartDocs será usado ao criar modelos ou importar novas APIs para um modelo.

Para restaurar o arquivo de modelo padrão do SmartDocs:

  1. Faça login no portal como usuário com privilégios de administrador ou de criação de conteúdo.
  2. Selecione Configuration > SmartDocs no menu de administração do Drupal.
  3. Expanda a área Configurações avançadas da página.
  4. Em "Fazer upload do modelo de método personalizado", clique em Remover, ao lado do arquivo do modelo personalizado do SmartDocs.
  5. Clique em Salvar configuração.

Como modificar o modelo do SmartDocs para um modelo individual

É possível modificar o modelo usado para um modelo individual.

Para modificar o modelo de um modelo individual:

  1. Faça login no portal como usuário com privilégios de administrador ou de criação de conteúdo.
  2. Selecione Content > SmartDocs no menu de administração do Drupal.
  3. No modelo que você quer editar, selecione Configurações em Operações.
  4. Na área Modelo de método, edite o modelo conforme necessário.
  5. Clique em Salvar modelo.
  6. Navegue até um nó do Drupal. As mudanças no modelo vão aparecer na página.

Como configurar o tipo de autenticação SmartDocs

As APIs definidas no SmartDocs podem ser abertas, o que significa que nenhuma credencial de autenticação é necessária para acessá-las, ou seguras. Para uma API segura, é necessário transmitir credenciais ao fazer uma chamada a ela.

Para uma API segura, o SmartDocs é compatível com os seguintes tipos de autenticação:

  • Autenticação básica: passe as credenciais básicas de autenticação como um par de nome de usuário e senha. Se você não especificar o uso do OAuth como o tipo de credencial, a API usará a autenticação básica por padrão.
  • OAuth 2.0: um provedor de serviços terceirizado autentica as credenciais do usuário, garante que ele tenha autorização para a API e emite um token de acesso. Quando você faz uma solicitação do SmartDocs para uma API protegida, o SmartDocs cria a solicitação e a envia ao provedor de serviços. Em seguida, o provedor de serviços valida o token e garante que ele não expirou.
  • Token personalizado: transmita um valor de token como cabeçalho ou parâmetro de consulta a cada solicitação.

Para cada tipo de autenticação, crie um esquema de segurança que defina as características da autenticação. Por exemplo, para autenticação de token personalizado, o esquema de segurança define como o token é transmitido (cabeçalho, parâmetro de consulta, parâmetro de corpo) e o nome do token.

Um esquema de segurança está associado a uma revisão específica de um modelo. Portanto, se você criar uma nova revisão de um modelo, será necessário redefinir os esquemas de segurança dela

Em um arquivo WADL, especifique se uma API exige autenticação usando a tag da Apigee <apigee:authentication>, conforme mostrado abaixo:

<method id="statusespublic_timeline" name="GET" apigee:displayName="PublicTimeline">
    ...
    <apigee:authentication required="true"/>
</method> 

Se a API estiver aberta, defina o atributo required como false.

Não é possível especificar o tipo de autenticação no arquivo WADL. Para fazer isso, edite o nó no Drupal. Para mais informações sobre os arquivos WADL, consulte a Referência de WADL.

Na página da API no Drupal, o SmartDocs adiciona o seguinte botão para permitir que os usuários especifiquem as credenciais básicas de autenticação:

Se você editar o nó para definir o tipo de autenticação como OAuth, o SmartDocs adicionará o seguinte botão à página:

Para tokens personalizados, o SmartDocs adiciona:

Como configurar a autenticação básica

Se você usar a autenticação básica com a API, só vai precisar especificar a tag <apigee:authentication> no arquivo WADL usado para criar o modelo.

Para aplicar a autenticação básica a métodos criados de uma origem diferente de um arquivo WADL:

  1. Faça login no portal como usuário com privilégios de administrador ou de criação de conteúdo.
  2. Selecione Conteúdo > SmartDocs no menu de administração do Drupal.
  3. Para o modelo pretendido, selecione Revisões da API em Operações.
  4. Na revisão do modelo que você quer editar, selecione Configurações de segurança em Operações.
  5. Selecione Adicionar esquema de segurança.
  6. Especifique o nome do esquema de segurança.
  7. Selecione Básico como o Tipo.
  8. Selecione Enviar.
  9. Para cada método no modelo, edite o método para definir o Esquema de segurança como o esquema básico.
    1. Selecione Conteúdo > SmartDocs no menu de administração do Drupal.
    2. Para o modelo pretendido, selecione Revisões da API em Operações.
    3. Na revisão de modelo que você quer editar, selecione Detalhes da revisão em Operações.
    4. Selecione Editar método para a API que você quer editar.
    5. Selecione o Esquema de segurança da API.
    6. Salve a API.

Como configurar a autenticação do OAuth 2.0

É possível configurar um modelo para usar o OAuth 2.0 no SmartDocs, em vez do padrão de autenticação básica. O OAuth pode ser configurado em dois locais:

  1. Crie um esquema de segurança para cada revisão de um modelo em Configurações de segurança para a revisão.
  2. Especifique o ID e a chave secreta do cliente para todas as revisões do modelo em Configurações.

Para ativar o OAuth:

  1. Faça login no portal como usuário com privilégios de administrador ou de criação de conteúdo.
  2. Selecione Conteúdo > SmartDocs no menu de administração do Drupal.
  3. Para o modelo pretendido, selecione Revisões da API em "Operações".
  4. Para a revisão de modelo que você quer editar, selecione Configurações de segurança em Operações.
  5. Selecione Adicionar esquema de segurança.
  6. Especifique o nome do esquema de segurança.
  7. Selecione OAuth 2.0 em Tipo.
  8. Defina o Tipo de concessão.
  9. Insira os valores nos campos URL de autorização. O URL de autorização é usado para receber o token de acesso.
  10. Defina o Verbo de autorização como GET ou POST.
  11. Informe o URL do token de acesso. O URL do token de acesso é usado para trocar o token de solicitação por um token de acesso.
  12. Digite o nome do parâmetro do token de acesso.
  13. Use In para especificar como transmitir o token: Header, Query ou Body.
  14. Defina os Escopos do OAuth.
  15. Selecione Enviar.
  16. Selecione Conteúdo > SmartDocs no menu de administração do Drupal.
  17. Para o modelo, selecione Configurações na lista suspensa Operações.
  18. Insira os valores de ID do cliente e Chave secreta do cliente.
  19. Selecione Salvar configurações de autenticação do modelo.
  20. Para cada método no modelo, edite o método para definir o Esquema de segurança como o esquema de segurança do OAuth.
    1. Selecione Conteúdo > SmartDocs no menu de administração do Drupal.
    2. Para o modelo pretendido, selecione Revisões da API em Operações.
    3. Na revisão de modelo que você quer editar, selecione Detalhes da revisão em Operações.
    4. Selecione Editar método para a API que você quer editar.
    5. Selecione o Esquema de segurança da API.
    6. Salve a API.

Como configurar a autenticação de tokens personalizados

É possível configurar um modelo para usar a autenticação de tokens personalizados.

Para ativar tokens personalizados:

  1. Faça login no portal como usuário com privilégios de administrador ou de criação de conteúdo.
  2. Selecione Conteúdo > SmartDocs no menu de administração do Drupal.
  3. Para o modelo pretendido, selecione Revisões da API em Operações.
  4. Na revisão do modelo que você quer editar, selecione Configurações de segurança em Operações.
  5. Selecione Adicionar esquema de segurança.
  6. Especifique o nome do esquema de segurança.
  7. Selecione Apikey como o Tipo.
  8. Defina o Nome do parâmetro que contém o token.
  9. Use In para especificar como transmitir o token: Header, Query ou Body.
  10. Selecione Enviar.
  11. Para cada método no modelo, edite o método para definir o Esquema de segurança como o seu esquema de token.
    1. Selecione Conteúdo > SmartDocs no menu de administração do Drupal.
    2. Para o modelo pretendido, selecione Revisões da API em Operações.
    3. Na revisão de modelo que você quer editar, selecione Detalhes da revisão em Operações.
    4. Selecione Editar método para a API que você quer editar.
    5. Selecione o Esquema de segurança da API.
    6. Salve a API.

exclusão de um modelo

Quando você exclui um modelo (Conteúdo > SmartDocs, Excluir no campo "Operações" no Drupal), ele é excluído da sua organização de Edge. Isso significa que, se outros portais fizerem referência ao modelo, ele não estará mais disponível. Para mais informações, consulte Sobre modelos e modelos SmartDoc.