Como usar o SmartDocs para documentar APIs

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

.

O SmartDocs permite documentar suas APIs no portal do desenvolvedor do Drupal 7 de modo a tornar Documentação da API totalmente interativa. Com a documentação interativa, os usuários do portal podem fazer o seguinte:

  • 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, você facilita o trabalho dos usuários do portal aprenda, teste e avalie suas APIs.

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

Exemplo do portal SmartDocs

Para usar o SmartDocs, você precisa ter um portal Apigee Developer Services. Para mais informações, consulte Como criar um desenvolvedor do Cloud Storage.

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

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

A API Hello World foi criada com base na simulação de OpenAPI Especificação, mocktarget.yaml. Para mais informações, consulte https://github.com/apigee/api-platform-samples/tree/master/default-proxies/helloworld/openapi.

A API Pet Store Example 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 View API Afirmation. O SmartDocs para este recurso é exibido:
  3. Clique em Enviar esta solicitação.
  4. Confira 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 Request para ver a solicitação ou no cURL. para visualizar a chamada de cURL correspondente.

Como documentar suas APIs usando SmartDocs

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

As etapas gerais para usar o SmartDocs são:

  1. Configure o módulo Drupal SmartDocs no portal.
  2. Crie um modelo do SmartDocs.
  3. Adicionar APIs ao modelo usando um arquivo WADL, OpenAPI (antigo Swagger) especificação ou manualmente.
  4. Renderizar o modelo como uma coleção de nós Drupal. Cada nó Drupal contém informações sobre uma única API. Por exemplo, se um recurso em sua API oferecer suporte a uma POST e uma solicitação PUT, o SmartDocs cria um nó Drupal separado para POST e PUT.
  5. Publique os nós Drupal. Após a publicação, os usuários do portal podem acessar e interagem com a API.
  6. Edite os nós Drupal antes ou depois de publicá-los. Você pode edite os nós Drupal usando o editor Drupal ou o arquivo WADL original ou especificação OpenAPI. Quando terminar de editar o arquivo WADL ou a especificação OpenAPI, importe no modelo como uma nova revisão e, em seguida, renderize e publique suas alterações.
  7. Ative o TLS. Como os SmartDocs podem enviar credenciais de autenticação para seus back-end como parte da solicitação para suas APIs, ative o TLS em seu portal para para garantir que essas credenciais são seguras. Nos ambientes de teste e produção do portal, A Apigee fornece o certificado TLS necessário para fazer solicitações https://. No entanto, antes de no seu portal, é necessário conseguir seu próprio certificado e ativar o TLS. Para mais informações, consulte Usar TLS no do Cloud Storage.

Sobre modelos e modelos de SmartDoc

Quando você cria um modelo no seu portal, ele é realmente armazenado no seu Edge organização, não na Drupal. Um modelo é um grande bloco de JSON com um nome interno (como "my-smartdocs-api") e define a estrutura de uma API. Por outro lado, o portal renderiza o modelo em HTML e fornece uma interface de edição para o modelo; Atualizações da API no portal são automaticamente retornados ao modelo de origem.

Armazenado na organização

Armazenado em Drupal

modelos

templates

Nós Drupal com funcionalidade de edição

Suponha que você tenha vários portais na organização (por exemplo, dev, stage e produção). No Pantheon, você move um portal de um ambiente para outro. Cada instância do parece que o portal contém o próprio modelo, mas todos fazem referência ao código-fonte um modelo de machine learning. Se você editar a API no 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 ficará mais disponível no a produção.

Os modelos controlam a aparência de seus SmartDocs e desses modelos (governados por Handlebars e arquivos CSS) são armazenados em 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 (o padrão da Apigee ou um modelo fornecido por você) é aplicado automaticamente aplicados 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 Drupal personalizado. Use o procedimento a seguir para configure o módulo SmartDocs.

Para configurar o módulo SmartDocs:

  1. Faça login no seu 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 módulos Drupal instalados são exibidos.
  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 garantir que a seção "Executar administração" tarefas para o módulo SmartDocs" para "Administrador" está ativada.
  7. Selecione Configuração > Portal do desenvolvedor na administração da 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 Configuração > Pesquisa e metadados > Aliases de URL > Settings no menu Drupal.
    2. Defina o Comprimento máximo do alias e o Componente máximo length como 255.
    3. Abra Pontuação.
    4. Para a chave esquerda ({) e a chave direita (}), selecione Nenhuma ação (não substituir).
    5. Clique em Save configuration.
  11. Se o portal do desenvolvedor for exposto a usuários em uma rede interna sem acesso a na Internet ou, se um subconjunto de APIs estiver em uma rede privada, configure a API SmartDocs URL de proxy da seguinte forma:
    1. Selecione Configuração > SmartDocs na 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 deve 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 Save configuration.

Como criar um modelo

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

Cada modelo especifica um nome interno único que também define o URL base do nós Drupal gerados. O URL de cada nó Drupal tem o seguinte formato:

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

em que:

  • 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 excluir.
  • resourcePath: o caminho do recurso.

Por exemplo, se você especificar o nome interno como "mymodel", o URL do modelo Nó Drupal para uma solicitação GET para um recurso chamado '/books' é:

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 de Edge como a origem da API. na estrutura dos preços. Para mais informações, consulte Sobre os modelos SmartDoc e de modelos.

  1. Faça login no seu portal como usuário com privilégios de administrador ou de criação de conteúdo.
  2. Selecione Conteúdo > SmartDocs na administração Drupal .
  3. Selecione Novo modelo na parte superior 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, os nomes nome é exibido. O nome interno do modelo que precisa ser único entre todos os modelos. O nome interno só pode ter letras minúsculas, números e hifens sem espaços. Selecione Editar para editar esse nome.
    • Descrição: uma descrição do modelo.
  5. Selecione Criar modelo.

Depois de criar o modelo, você será redirecionado para a página do modelo. A partir daí, você pode usar a lista suspensa Operações bx para:

  • Importe um arquivo WADL que descreva a API ou especifique o URL de uma Especificação que descreve sua API.
  • Adicionar revisão ao modelo
  • Modifique as Configurações do modelo, incluindo as folhas de estilo usadas pelo um modelo de machine learning.
  • Exporte o modelo para um arquivo.
  • Exclua o modelo.

Como adicionar APIs a um modelo

É possível adicionar APIs a um modelo das seguintes formas:

  • Importar um arquivo WADL que contém a definição da API
  • Importar uma especificação OpenAPI (OpenAPI 2.0 ou 1.2)
  • Como criar recursos e métodos manualmente

Também é possível importar um arquivo JSON do SmartDocs para um modelo. Esse arquivo é normalmente criado por primeiro exportando um modelo existente, editando o arquivo e, em seguida, importando as atualizações. Para mais informações, consulte "Como exportar e importar um modelo" a seguir.

Vídeo:assista a um vídeo curto para aprender a 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. Todas sempre que você importa um arquivo WADL, cria automaticamente uma nova revisão do modelo.

  1. Faça login no seu portal como usuário com privilégios de administrador ou de criação de conteúdo.
  2. Selecione Conteúdo > SmartDocs na biblioteca Drupal no menu de administração.
  3. Selecione o modelo que você quer atualizar.
  4. Em Operações, selecione Importar.
  5. Selecione WADL no menu suspenso Escolher formato no página de importação do SmartDocs.
  6. Selecione Arquivo ou URL na coluna Fazer upload Menu suspenso "Tipo".
    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 importá-lo para o modelo. Agora é possível para renderizar o modelo.
  8. Você será redirecionado para a página de informações do modelo, onde será possível renderizar o um modelo de machine learning.

Importar uma OpenAPI Especificação

Depois de criar um modelo, é possível importar uma OpenAPI (anteriormente Swagger) Especificação. 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, você cria automaticamente uma nova revisão do modelo.

Para importar uma especificação OpenAPI:

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

Criar recursos manualmente e métodos

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ê usa um arquivo WADL ou especificação OpenAPI para criar seu modelo, use este procedimento para editar suas APIs, inclusive adicionar novas APIs, depois 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. ou seja, todas as APIs de 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 de "/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 invocada em um recurso. Por exemplo, para "/login" você tem suporte para POST para login e DELETE para logout. O recurso não é compatível com 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 a mesma Os URLs são definidos em um único recurso no SmartDocs.

Como regra geral:

  • Crie um modelo de SmartDocs diferente para cada caminho base exclusivo na API.
  • Defina um recurso SmartDocs diferente para cada recurso exclusivo na API.
  • Definir 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 será possível adicionar o recurso. Se o modelo for novo e não tiver revisões, crie um novo revisão.

Para criar uma nova revisão de um modelo:

  1. Faça login no seu portal como usuário com privilégios de administrador ou de criação de conteúdo.
  2. Selecionar Conteúdo > SmartDocs no 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 de API, insira as seguintes informações:
    • Nome de exibição: o nome da revisão como aparece no no portal do Google Cloud.
    • 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 pode usar diferentes URLs base para cada revisão. Por exemplo, você inclui uma versão no URL base. Para a primeira revisão de modelo, o URL base é:
      https://myCompany.com/v1
      Para a próxima revisão, o URL base poderia 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 caminho de recurso, que é combinado com o URL base na revisão do modelo para criar o URL completo do recurso.

Para definir um recurso:

  1. Faça login no seu portal como usuário com privilégios de administrador ou de criação de conteúdo.
  2. Selecionar Conteúdo > SmartDocs no no menu de administração do Drupal.
  3. Para o modelo que você quer atualizar, em Operações, selecione API Revisões para conferir todas as revisões de um modelo.
  4. Selecione uma revisão para editar.
  5. Na página de revisão, selecione Adicionar recurso no menu suspenso.
  6. Na página Add Resource, 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 base da revisão do modelo. para criar o URL completo do recurso.
    • Descrição: uma descrição do recurso.
    • Parâmetros: como opção, 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 define métodos no recurso.

Também é possível adicionar parâmetros ao recurso, como modelo, consulta e cabeçalho parâmetros. Todos os parâmetros de recursos 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 ele precisa oferecer suporte a esse parâmetro de consulta.

Como alternativa, é possível definir parâmetros em um método. Por exemplo, um método POST pode oferecer suporte parâmetros de consulta incompatíveis com o método DELETE. Portanto, adicione quaisquer parâmetros específico de um método ao definir esse método, conforme descrito abaixo.

A imagem a seguir mostra uma página do SmartDocs existente para o API Aprovar ou revogar do aplicativo do desenvolvedor da Apigee com cada tipo de parâmetro destacado:

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": verdadeiro,
"tipo": "MODELO"
}

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

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

Consulta

{
"dataType": "string",
"defaultValue": "",
"description": "Local.",
"name": "w",
"required": verdadeiro,
"type": "QUERY"
}

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

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 de modelo define uma variável no caminho do recurso. Por exemplo, você define duas de modelos no recurso. Observe como cada definição de parâmetro na matriz de parâmetros é separado 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 de caminho do recurso, incluída 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 a parte org_name e developer_email do URL antes eles podem 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 podem ser invocados 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 os parâmetros usados por ele, incluindo consultas e parâmetros de cabeçalho. Consulte a descrição acima para conferir o recurso e saber como adicionar parâmetros a um método.

A imagem a seguir mostra uma página do SmartDocs para a API Create Developer da Apigee com o cada área da página destacada com o valor correspondente que você definiu ao definir um :

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

Como renderizar um modelo

Depois de adicionar APIs a um modelo, é possível renderizá-lo. A renderização converte o descrição da API em nós Drupal. Quando a renderização for concluída, você terá uma única nó para cada API, em que cada nó Drupal corresponde a uma página HTML.

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

Para renderizar um modelo:

  1. Faça login no seu portal como usuário com privilégios de administrador ou de criação de conteúdo.
  2. Selecionar Conteúdo > SmartDocs no no menu de administração do Drupal.
  3. Para o modelo que você quer renderizar, selecione Revisões de API em Operações.
  4. Selecione a revisão que você quer renderizar. Você só pode renderizar nós de uma única revisão do o modelo.
  5. Selecione os métodos a serem renderizados.
  6. Selecione Render Nodes na guia Update. menu suspenso de opções.
  7. Clique em Atualizar.
  8. Uma tela de carregamento vai aparecer para mostrar o progresso da renderização dos nós.
    Após a renderização dos nós, o ID do nó Drupal para cada API aparece sob o Coluna Associação de nós do modelo. Clique no link do Nó Associação 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ó Drupal.

Publicando nós

Um nó não é visível para os usuários do portal até que seja publicado. Você também pode optar por os nós publicados durante o processo de renderização. Se optar por não publicar os nós, você elas precisam ser publicadas manualmente após a renderização ser concluída.

Para publicar um nó:

  1. Faça login no seu portal como usuário com privilégios de administrador ou de criação de conteúdo.
  2. Selecionar Conteúdo > SmartDocs no no menu de administração do Drupal.
  3. Para o modelo que você quer publicar, selecione Revisões de 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 de publicação.
  6. Selecione os nós na revisão a ser publicada.
  7. Selecione os Publish Nodes na guia Update. menu suspenso de opções.
  8. Clique em Atualizar.
  9. Navegue até o nó selecionando o ID dele em Associação de nós .

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

  1. Faça login no seu portal como usuário com privilégios de administrador ou de criação de conteúdo.
  2. Selecione Configuração > Pesquisa e metadados > Aliases de URL > Padrões 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.

Por causa do armazenamento em cache no portal, suas páginas de modelo podem não aparecer imediatamente após a publicação. Se necessário, você pode limpar manualmente o cache HTML do SmartDocs usando o comando procedimento a seguir:

  1. Faça login no seu portal como usuário com privilégios de administrador ou de criação de conteúdo.
  2. Selecione Configuração > SmartDocs na administração Drupal .
  3. Clique em Recriar caches do modelo 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 para usuários do portal.

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

  1. Faça login no seu portal como usuário com privilégios de administrador ou de criação de conteúdo.
  2. Selecionar Conteúdo > SmartDocs no no menu de administração do Drupal.
  3. Para o modelo que você quer cancelar, selecione Revisões de API em Operações.
  4. Selecione a revisão de modelo do nó da publicação.
  5. Selecione os nós na revisão para cancelar a publicação.
  6. Selecione os nós Cancelar publicação na guia Atualizar. menu suspenso de opções.
  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 em um modelo atual 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 atualmente publicados.

É 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 as revisões. No entanto, publicar uma API em um modelo que é igual a um nó publicado em outro modelo cancela a publicação do nó mais antigo da API e a substitui pela versão mais recente publicada API.

Para ver a revisão de um modelo:

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

Como editar um nó

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

Também é possível editar o arquivo WADL original ou a especificação OpenAPI. Quando você terminar de editar, importar o arquivo WADL ou a especificação OpenAPI de volta para o modelo como uma nova revisão e depois renderize e publique as mudanças conforme descrito acima.

Para editar um nó usando o editor Drupal:

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

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

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

Para excluir um nó:

  1. Faça login no seu portal como usuário com privilégios de administrador ou de criação de conteúdo.
  2. Selecione Conteúdo > SmartDocs no no menu de administração do Drupal.
  3. Para o modelo que você quer atualizar, selecione Revisões de API em Operações.
  4. Selecione a revisão do modelo que você quer publicar.
  5. Selecione Delete method em o menu suspenso Operações do método.
    Cuidado:a exclusão do nó também remove a API do modelo. Se você só Quer cancelar a publicação da API para que ela fique oculta para os usuários do portal, mas não quer 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 SmartDocs que não se referem mais a métodos válidos do modelo. Acesse o relatório por selecionando Reports no menu Drupal e selecionando o relatório chamado Status do nó do SmartDocs.

Como exportar e importar um modelo

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

A importação de um modelo cria uma nova revisão do modelo. O SmartDocs tenta corresponder APIs no modelo com APIs importadas. Se o SmartDocs detectar uma correspondência, a importação atualizará o Drupal nó correspondente à API atual. Se o SmartDocs não detectar uma correspondência, a importação cria 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, importar um modelo, e o SmartDocs detecta uma correspondência de uma API POST no modelo importado para o modelo atual API POST. Todas as atualizações na API POST atualizam o nó do Drupal 91. Se o SmartDocs não detectar uma corresponder, ele cria um novo nó Drupal com um novo ID.

A Drupal realiza 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 EXCLUIR.
  • resourcePath: o caminho do recurso.
  • query params: todos os parâmetros de consulta usados pela API.

Se todas as quatro características de uma API importada corresponderem a uma API atual no modelo, O SmartDocs atualiza o nó Drupal atual.

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, em seguida, o modelo de novo. 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 seu portal como usuário com privilégios de administrador ou de criação de conteúdo.
  2. Selecionar Conteúdo > SmartDocs no 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ê será solicitado a salvar o arquivo em disco ou abri-lo em um editor.

Para importar um modelo:

  1. Faça login no seu portal como usuário com privilégios de administrador ou de criação de conteúdo.
  2. Selecionar Conteúdo > SmartDocs no no menu de administração do Drupal.
  3. Para o modelo que você quer importar, selecione Importar na Operações.
  4. Selecione JSON do SmartDocs no menu suspenso Escolher formato.
  5. Selecione Arquivo ou URL em o Tipo de upload:
    1. Se você selecionar Arquivo, procure o arquivo JSON.
    2. Se você selecionar URL, especifique o URL do arquivo JSON do SmartDocs.
  6. Clique em Importar para importá-lo para o modelo.
  7. Você será redirecionado para a página de informações do modelo, onde será possível renderizar o um modelo de machine learning. A importação cria uma nova revisão do modelo.
  8. Renderizar e publicar os nós.

Como editar o modelo do SmartDocs

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

O modelo SmartDocs inclui um arquivo de modelo codificado como um arquivo .hbr do Handlebars, arquivos CSS, e JavaScript. Com os Handlebars, grande parte do conteúdo é orientada por variáveis usando expressões do guidão, como &123;&123;body}}. Uma lista dos elementos As expressões do Handlebar são fornecidas em um comentário na parte superior do arquivo. Para informações sobre usando o Handlebars para personalizar os modelos, consulte http://handlebarsjs.com.

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

Como fazer upload de um Arquivo de modelo do SmartDocs

Você pode fazer upload de um arquivo de modelo SmartDocs personalizado, como um arquivo .hbr do Handlebars, para usar como o modelo padrão ao criar novos modelos ou importar novas APIs para um modelo.

Se quiser usar o arquivo de modelo padrão do SmartDocs como ponto de partida ao criar seu arquivo de modelo personalizado do SmartDocs, poderá fazer 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 seu portal como usuário com privilégios de administrador ou de criação de conteúdo.
  2. Selecione Configuração > SmartDocs no repositório do Drupal no menu de administração.
  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. navegue até o arquivo .hbr do Handlebars.
  5. Clique em Fazer upload.
  6. Clique em Save configuration.

Restauração do arquivo de modelo padrão do SmartDocs

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

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

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

Modificando o modelo SmartDocs para um modelo individual

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

Para modificar o modelo para um modelo individual:

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

Como configurar o Tipo de autenticação do SmartDocs

As APIs definidas no SmartDocs podem ser abertas, o que significa que nenhuma credencial de autenticação é necessários para acessá-las ou protegê-las. Uma API segura exige que você passe credenciais ao fazer uma chamada para a API.

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

  • Autenticação básica: transmita credenciais básicas de autenticação como um nome de usuário e senha. Se você não especificar o uso de OAuth como o tipo de credencial, a API o padrão é usar a autenticação básica.
  • OAuth 2.0: um provedor de serviços terceirizado autentica a autenticação do de acesso, garante que o usuário tenha autorização para a API e emite uma solicitação de acesso com base no token correto anterior. Quando você faz uma solicitação do SmartDocs para uma API protegida, o SmartDocs cria a solicitação e e o envia para o provedor de serviços. 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 para cada solicitação.

Para cada tipo de autenticação, você cria um esquema de segurança que define a e as características da autenticação. Por exemplo, para autenticação de token personalizado, a esquema de segurança define como o token é transmitido (cabeçalho, parâmetro de consulta, parâmetro do corpo) e o nome do o 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, você terá que redefinir os esquemas de segurança para essa revisão

Em um arquivo WADL, especifique se uma API exige autenticação usando a tag da Apigee &lt;apigee:authentication&gt;, conforme mostrados 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. Você faz isso ao editar o nó no Drupal. Para mais informações sobre arquivos WADL, consulte WADL Referência.

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

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

Para tokens personalizados, o SmartDocs adiciona:

Como configurar autenticação básica

Se você usar a autenticação básica com a API, só precisará especificar a tag &lt;apigee:authentication&gt; na WADL que será 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 seu portal como usuário com privilégios de administrador ou de criação de conteúdo.
  2. Selecione Conteúdo > SmartDocs no no menu de administração do Drupal.
  3. Para o modelo desejado, selecione Revisões de API em Operações.
  4. Na revisão do modelo que você quer editar, selecione Segurança Configurações 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 respectivo Esquema de segurança. ao esquema básico.
    1. Selecione Conteúdo > SmartDocs no no menu de administração do Drupal.
    2. Para o modelo desejado, selecione Revisões de API em Operações.
    3. Para a revisão de modelo que você quer editar, selecione Revisão Detalhes em Operações.
    4. Selecione Edit Method para a API que você quer editar.
    5. Selecione o Esquema de segurança para a API.
    6. Salve a API.

Como configurar Autenticação do OAuth 2.0

É possível configurar um modelo para usar OAuth 2.0 no SmartDocs, em vez do padrão autenticação. Você configura o OAuth em dois locais:

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

Para ativar o OAuth:

  1. Faça login no seu portal como usuário com privilégios de administrador ou de criação de conteúdo.
  2. Selecione Conteúdo > SmartDocs no no menu de administração do Drupal.
  3. Para o modelo desejado, selecione Revisões de API em "Operações".
  4. Na revisão do modelo que você quer editar, selecione Configurações de segurança na Operações.
  5. Selecione Adicionar esquema de segurança.
  6. Especifique o nome do esquema de segurança.
  7. Selecione OAuth 2.0 como o Tipo.
  8. Defina o Tipo de concessão.
  9. Digite os valores nos campos URL de autorização. A autorização O URL é usado para obter o token de acesso.
  10. Defina Authorization Verb como GET ou POST.
  11. Digite o URL do token de acesso. O URL do Token de Acesso é o URL 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 OAuth.
  15. Selecione Enviar.
  16. Selecione Conteúdo > SmartDocs no no menu de administração do Drupal.
  17. Para o modelo, selecione Configurações em Operações no menu suspenso.
  18. Insira os valores em ID do cliente e Cliente Secret.
  19. Selecione Salvar configurações de autenticação do modelo.
  20. Para cada método no modelo, edite o método para definir o respectivo Esquema de segurança. ao esquema de segurança OAuth.
    1. Selecione Conteúdo > SmartDocs no no menu de administração do Drupal.
    2. Para o modelo desejado, selecione Revisões de API em Operações.
    3. Para a revisão de modelo que você quer editar, selecione Revisão Detalhes em Operações.
    4. Selecione Edit Method para a API que você quer editar.
    5. Selecione o Esquema de segurança para a API.
    6. Salve a API.

Como configurar a autenticação de token personalizado

É possível configurar um modelo para usar a autenticação por token personalizado.

Para ativar tokens personalizados:

  1. Faça login no seu portal como usuário com privilégios de administrador ou de criação de conteúdo.
  2. Selecione Conteúdo > SmartDocs no no menu de administração do Drupal.
  3. Para o modelo desejado, selecione Revisões de API em Operações.
  4. Na revisão do modelo que você quer editar, selecione Segurança Configurações 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 token: Header, Query, ou Body.
  10. Selecione Enviar.
  11. Para cada método no modelo, edite o método para definir o respectivo Esquema de segurança. ao esquema de token.
    1. Selecione Conteúdo > SmartDocs no no menu de administração do Drupal.
    2. Para o modelo desejado, selecione Revisões de API em Operações.
    3. Para a revisão de modelo que você quer editar, selecione Revisão Detalhes em Operações.
    4. Selecione Edit Method para a API que você quer editar.
    5. Selecione o Esquema de segurança para a API.
    6. Salve a API.

exclusão de um modelo

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