Cómo usar SmartDocs para documentar las API

Estás consultando la documentación de Apigee Edge.
Consulta la documentación de Apigee X.
Información

SmartDocs te permite documentar tus APIs en el portal para desarrolladores de Drupal 7 de una manera que hace que la documentación de la API sea completamente interactiva. La documentación interactiva permite que los usuarios del portal puedan hacer lo siguiente:

  • Lee sobre tus APIs
  • Envía una solicitud en vivo a tu API
  • Visualiza una respuesta en vivo que muestra la API

Mediante la creación de una documentación interactiva sobre tus APIs, permites que el usuario del portal aprenda, pruebe y evalúe tus APIs con facilidad.

La API de Edge Management es una API de RESTful que te permite acceder a los servicios de las APIs con cualquier cliente HTTP. Apigee usa SmartDocs para crear documentación interactiva para la API de administración de Edge. Consulte la documentación de la API aquí.

Ejemplo de portal de SmartDocs

Si quieres usar SmartDocs, debes tener un portal de servicios para desarrolladores de Apigee. Si deseas obtener más información, consulta Cómo crear un portal para desarrolladores.

En la página principal del portal para desarrolladores, haz clic en APIs en la barra de navegación superior para ver la página Documentación de la API.

Hay dos APIs documentadas en el portal: Hello World y Pet Store Example.

La API de Hello World se creó a partir de la especificación de OpenAPI de destino simulada, mocktarget.yaml. Para obtener más información, consulta https://github.com/apigee/api-platform-samples/tree/master/default-proxies/helloworld/openapi.

La API de ejemplo de Pet Store se creó a partir de la demostración clásica de la tienda de mascotas.

Explora la API de Hello World:

  1. Haz clic en API de Hello World. Se muestra la página de resumen de la API de Hello World:
  2. Haz clic en Ver la afirmación de la API. Se muestran los SmartDocs para este recurso:
  3. Haz clic en Enviar esta solicitud.
  4. Consulta la respuesta que se muestra:
    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. Haz clic en la pestaña Request para ver la solicitud o en la pestaña cURL para ver la llamada cURL correspondiente.

Cómo documentar tus APIs con SmartDocs

SmartDocs representa tus APIs mediante un model, en el que el modelo contiene toda la información sobre tus APIs. El portal extrae información sobre las APIs del modelo para renderizar las páginas de documentación del portal como nodos de Drupal, en los que cada nodo de Drupal corresponde a una página de documentación en el portal.

Los pasos generales que debes seguir para usar SmartDocs son los siguientes:

  1. Configura el módulo de SmartDocs de Drupal en el portal.
  2. Crear un modelo de SmartDocs
  3. Agrega APIs al modelo desde un archivo WADL, una especificación de OpenAPI (anteriormente Swagger) o de forma manual.
  4. Renderiza el modelo como una colección de nodos de Drupal. Cada nodo de Drupal contiene información sobre una sola API. Por ejemplo, si un recurso de la API admite tanto una solicitud POST como una PUT, SmartDocs creará un nodo de Drupal independiente para POST y PUT.
  5. Publica los nodos de Drupal. Una vez publicada, los usuarios del portal pueden ver y también interactuar con la API.
  6. Edita los nodos de Drupal, ya sea antes o después de publicarlos. Para editar los nodos de Drupal, puedes usar el editor de Drupal o editar el archivo WADL original o la especificación de OpenAPI. Cuando termines de editar el archivo WADL o la especificación de OpenAPI, impórtalos al modelo como una revisión nueva y, luego, procesa y publica los cambios.
  7. Habilita TLS. Debido a que SmartDocs puede enviar credenciales de autenticación a tu backend como parte de realizar una solicitud a tus APIs, debes habilitar TLS en tu portal para asegurarte de que esas credenciales sean seguras. En los entornos de producción y prueba del portal, Apigee proporciona el certificado TLS necesario para realizar solicitudes https://. Sin embargo, antes de publicar tu portal, debes obtener tu propio certificado TLS y habilitar TLS. Para obtener más información, consulta Usa TLS en el portal.

Acerca de las plantillas y los modelos de SmartDoc

Cuando creas un modelo en tu portal, este se almacena en realidad en tu organización de Edge, no en Drupal. Un modelo es un gran bloque de JSON con un nombre interno (como "my-smartdocs-api") y define la estructura de una API. Por otro lado, tu portal procesa el modelo en HTML y le proporciona una interfaz de edición al modelo. Cualquier actualización de la API en el portal se envía automáticamente al modelo de origen.

Almacenado en la organización

Almacenado en Drupal

ajustables

templates

Nodos de Drupal con funcionalidad de edición

Supongamos que tienes varios portales en tu organización (por ejemplo, desarrollo, etapa de pruebas y producción). En Pantheon, mueves un portal de un entorno a otro. Parece que cada instancia del portal contiene su propio modelo, pero todas ellas en realidad hacen referencia al modelo fuente. Si editas la API en dev, el modelo se actualiza y los cambios aparecen en producción. Del mismo modo, si borras un modelo en desarrollo, se borrará la fuente y ya no estará disponible en producción.

Las plantillas controlan la apariencia de tus SmartDocs, y esas plantillas (controladas por Handlebars y archivos CSS) se almacenan con cada instancia del portal. Por lo tanto, en teoría, cada portal puede usar una plantilla única para cada modelo. Sin embargo, una de las ventajas del framework de procesamiento es que se aplica de forma automática una plantilla predeterminada (ya sea la predeterminada de Apigee o una que proporciones) a cada modelo.

En el siguiente diagrama, se muestra la relación entre los modelos y los portales. Las flechas verdes muestran la sincronización automática.

Con el siguiente comando de cURL, se enumeran todos los modelos de tu organización:

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

Cómo configurar el módulo SmartDocs

Apigee implementó SmartDocs como un módulo personalizado de Drupal. Usa el siguiente procedimiento para configurar el módulo de SmartDocs.

Para configurar el módulo SmartDocs, haz lo siguiente:

  1. Accede a tu portal como un usuario con privilegios de administrador o de creación de contenido.
  2. Selecciona Modules en el menú de administración de Drupal. Aparecerá la lista de todos los módulos de Drupal instalados.
  3. Habilita el módulo SmartDocs.
  4. Guarde la configuración.
  5. En el menú de administrador de Drupal, selecciona Modules.
  6. Selecciona SmartDocs -> Permisos y asegúrate de que la opción “Realizar tareas de administración para el módulo SmartDocs” esté habilitada para la función “Administrador”.
  7. Selecciona Configuración > Portal para desarrolladores en el menú de administración de Drupal.
  8. Establece el Tiempo de espera de la conexión y el Tiempo de espera de la solicitud en 16 segundos.
  9. Guarde la configuración.
  10. Establece la configuración de las URLs:
    1. En el menú de Drupal, selecciona Configuración > Búsqueda y metadatos > Alias de URL > Configuración.
    2. Establece la Longitud máxima de alias y la Longitud máxima de los componentes en 255.
    3. Expande Puntuación.
    4. En el caso de las opciones de llave izquierda ({) y llave derecha (}), selecciona Sin acción (no reemplazar).
    5. Haga clic en Guardar configuración.
  11. Si tu portal para desarrolladores se expondrá a usuarios en una red interna sin acceso a Internet o si un subconjunto de tus APIs está en una red privada, configura la URL del proxy de la API de SmartDocs de la siguiente manera:
    1. Selecciona Configuración > SmartDocs en el menú Administración de Drupal.
    2. Expanda la opción Configuración avanzada.
    3. Actualiza el campo URL del proxy de SmartDocs como se indica a continuación: <host>/smartdocs/v1/sendrequest.
      La ayuda intercalada debe proporcionar el valor requerido para tu entorno. Por ejemplo:
      https://api-us-east-1-enterprise.apigee.com/smartdocs/v1/sendrequest

      El valor predeterminado de este campo es https://apiconsole-prod.apigee.net/smartdocs/v1/sendrequest
    4. Haga clic en Guardar configuración.

Crea un modelo

Un modelo contiene toda la información sobre la representación de tu API. Puedes definir varios modelos en el portal para admitir diferentes APIs o agrupar todas tus APIs en un solo modelo.

Cada modelo especifica un nombre interno único que también define la URL base de los nodos de Drupal generados. La URL de cada nodo de Drupal tendrá el siguiente formato:

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

Donde:

  • drupalBasePath: Es la URL base del portal.
  • internalName: Es el nombre interno del modelo.
  • httpMethod: El método HTTP de la API, como get, put, post o delete.
  • resourcePath: La ruta de acceso del recurso.

Por ejemplo, si especificas el nombre interno como “mymodel”, la URL del nodo de Drupal generado para una solicitud GET a un recurso llamado “/books” es la siguiente:

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

Cómo crear un modelo

Cuando creas un modelo, se almacena en tu organización de Edge como la fuente de la estructura de la API. Para obtener más información, consulta Acerca de las plantillas y los modelos de SmartDoc.

  1. Accede a tu portal como un usuario con privilegios de administrador o de creación de contenido.
  2. En el menú de administración de Drupal, selecciona Contenido > SmartDocs.
  3. Selecciona Modelo nuevo en la parte superior de la página.
  4. Ingresa los siguientes campos:
    • Nombre: El nombre del modelo que se mostrará en el sitio.
    • Nombre interno: A medida que escribes el Nombre, aparece el nombre interno. El nombre interno del modelo que debe ser único entre todos los modelos. El nombre interno debe contener solo letras minúsculas, números y guiones sin espacios. Selecciona Editar para modificar este nombre.
    • Descripción (Description): una descripción del modelo.
  5. Selecciona Crear modelo.

Después de crear el modelo, se te redireccionará a su página. Desde allí, puedes usar el menú desplegable Operations (Operaciones) bx para realizar las siguientes acciones:

  • Importa un archivo WADL que describa tu API o especifica la URL de una especificación de OpenAPI que la describa.
  • Agregar revisión al modelo
  • Modifica la Configuración del modelo, incluidas las hojas de estilo que usa el modelo.
  • Exporta el modelo a un archivo.
  • Borra el modelo.

Agrega APIs a un modelo

Puedes agregar APIs a un modelo de las siguientes maneras:

  • Importa un archivo WADL que contiene la definición de la API
  • Cómo importar una especificación de OpenAPI (OpenAPI 2.0 o 1.2)
  • Crea recursos y métodos de forma manual

También puedes importar un archivo JSON de SmartDocs a un modelo. Por lo general, este archivo se crea primero cuando se exporta un modelo existente, se edita el archivo y, luego, se importan las actualizaciones. Para obtener más información, consulta “Importa y exporta un modelo” a continuación.

Video: Mira un video breve para aprender a agregar API a un modelo de SmartDocs mediante la importación de una especificación de OpenAPI.

Cómo importar un WADL

Una vez que hayas creado correctamente un modelo, importa un archivo WADL que describa tu API. Cada vez que importas un archivo WADL, creas automáticamente una revisión nueva del modelo.

  1. Accede a tu portal como un usuario con privilegios de administrador o de creación de contenido.
  2. Selecciona Content > SmartDocs en el menú de administración de Drupal.
  3. Selecciona el modelo que deseas actualizar.
  4. En Operaciones, selecciona Importar.
  5. Selecciona WADL en el menú desplegable Elegir formato de la página de importación de SmartDocs.
  6. Selecciona Archivo o URL en el menú desplegable Tipo de carga.
    1. Si seleccionas Archivo, busca el archivo WADL.
    2. Si seleccionas URL, especifica la URL del archivo WADL.
  7. Haz clic en Importar para importarlo al modelo. Ahora puedes renderizar el modelo.
  8. Se te redireccionará a la página de información del modelo, en la que ahora puedes renderizarlo.

Importa una especificación de OpenAPI.

Después de crear correctamente un modelo, puedes importar una especificación de OpenAPI (anteriormente Swagger). Edge admite las versiones 1.2 y 2.0 de OpenAPI.

OpenAPI usa archivos que contienen objetos JSON para describir una API. Cada vez que importas una especificación de OpenAPI, creas automáticamente una revisión nueva del modelo.

Para importar una especificación de OpenAPI, haz lo siguiente:

  1. Accede a tu portal como un usuario con privilegios de administrador o de creación de contenido.
  2. Selecciona Contenido > SmartDocs en el menú de administración de Drupal.
  3. Selecciona el modelo que deseas actualizar.
  4. En Operaciones, selecciona Importar.
  5. Selecciona Swagger JSON o Swagger YAML en el menú desplegable de Elegir formato en la página de importación de SmartDocs.
  6. Selecciona Archivo o URL en el menú desplegable Tipo de carga (debes seleccionar URL para OpenAPI 1.2).
    1. Si seleccionas File, navega hasta la OpenAPI Specification.
    2. Si seleccionas URL, especifica la URL de la especificación de OpenAPI.
  7. Haz clic en Importar para importarlo al modelo.
  8. Se te redireccionará a la página de información del modelo, en la que ahora puedes renderizarlo.

Cómo crear recursos y métodos de forma manual

Si no tienes un archivo WADL o una especificación de OpenAPI que no represente a tu API, puedes agregar APIs a tu modelo de forma manual. Además, si usas un archivo WADL o una especificación de OpenAPI para crear tu modelo, puedes usar este procedimiento a fin de editar tus API, incluso agregar nuevas API, después de la importación.

Para agregar una API de forma manual, sigue estos pasos:

  1. Crea una revisión nueva del modelo.

    Cuando creas la revisión, especificas la única ruta de acceso base de todas las APIs en el modelo, lo que significa que todas las APIs de un modelo comparten la misma ruta base. Por ejemplo, especifica la ruta base de la siguiente manera:

    https://myCompany.com/v1

    Cuando agregas recursos al modelo, se extiende la ruta base.
  2. Define uno o más recursos para el modelo. La ruta del recurso se combina con la ruta base de la revisión del modelo para especificar la URL completa del recurso. Por ejemplo, si tu recurso define una ruta de acceso "/login", la URL completa del recurso es:

    https://myCompany.com/v1/login
  3. Define uno o más métodos para cada recurso. Un método especifica el verbo HTTP que se puede invocar en un recurso. Por ejemplo, en el caso del recurso "/login", admites POST para el acceso y DELETE para salir. Este recurso no admite otros verbos HTTP, como PUT o GET. Por lo tanto, define dos métodos para el recurso: uno para POST y otro para DELETE.

    El método usa la URL de recurso de su recurso superior. Por lo tanto, todos los métodos con la misma URL se definen en un único recurso en SmartDocs.

Como regla general, ten en cuenta lo siguiente:

  • Crea un modelo de SmartDocs diferente para cada ruta base única en tu API.
  • Define un recurso SmartDocs diferente para cada recurso único en tu API.
  • Define un método de SmartDocs diferente para cada verbo HTTP compatible con un recurso.

Crea una revisión nueva de un modelo

Solo puedes agregar un recurso a una revisión existente de un modelo. Si el modelo ya tiene una revisión, puedes agregar tu recurso. Si el modelo es nuevo y no tiene revisiones, crea una revisión nueva.

Para crear una revisión nueva de un modelo, haz lo siguiente:

  1. Accede a tu portal como un usuario con privilegios de administrador o de creación de contenido.
  2. Selecciona Contenido > SmartDocs en el menú de administración de Drupal.
  3. Para el modelo que deseas actualizar, selecciona Agregar revisión en Operaciones.
  4. En la página Agregar revisión de API, ingresa la siguiente información:
    • Display Name (Nombre visible): Es el nombre de la revisión tal como aparece en el portal.
    • ID de versión: Es un identificador corto para la revisión.
    • Descripción: Es una descripción de la revisión.
    • URL base: La URL base de todas las APIs en la revisión del modelo. Un modelo puede usar diferentes URL base para cada revisión. Por ejemplo, incluye un indicador de versión en la URL base. Para la primera revisión del modelo, la URL base es:
      https://myCompany.com/v1
      Para la próxima revisión, la URL base podría ser:
      https://myCompany.com/v2
  5. Selecciona Agregar revisión. Se te redireccionará a la página de revisión del modelo. Ahora puedes definir recursos en el modelo.

Define un recurso

Un recurso especifica la URL completa de una API. Cuando defines un recurso, especificas la ruta de acceso del recurso, que se combina con la URL base en la revisión del modelo para crear la URL completa del recurso.

Para definir un recurso, haz lo siguiente:

  1. Accede a tu portal como un usuario con privilegios de administrador o de creación de contenido.
  2. Selecciona Contenido > SmartDocs en el menú de administración de Drupal.
  3. En el modelo que deseas actualizar, en Operaciones, selecciona Revisiones de API para ver todas las revisiones de un modelo.
  4. Selecciona una revisión para editar.
  5. En la página de revisión, seleccione Agregar recurso en el menú desplegable.
  6. En la página Agregar recurso, ingresa la siguiente información:
    • Display Name (Nombre visible): El nombre del recurso.
    • Ruta de acceso: La ruta de acceso del recurso, que comienza con “/”. El valor de Path se combina con la URL base de la revisión del modelo para crear la URL completa del recurso.
    • Descripción: Es una descripción del recurso.
    • Parámetros: De manera opcional, ingresa el objeto JSON que define cada parámetro en el recurso. Estos parámetros se describen a continuación.
  7. Selecciona Agregar recurso. Se te redireccionará a la página del modelo. Ahora puedes definir métodos en el recurso.

De manera opcional, puedes agregar parámetros al recurso, como parámetros de plantilla, consulta y encabezado. Todos los parámetros de recursos los hereda cualquier método definido en ese recurso. Por lo tanto, si defines un parámetro de consulta en el recurso, todos los métodos agregados a ese recurso deben admitirlo.

Como alternativa, puedes definir parámetros en un método. Por ejemplo, un método POST puede admitir parámetros de consulta que no son compatibles con un método DELETE. Por lo tanto, agrega cualquier parámetro específico de un método cuando lo defines, como se describe a continuación.

En la siguiente imagen, se muestra una página de SmartDocs existente para la API de Apigee Aprobar o Revocar app de desarrollador con cada tipo de parámetro destacado:

Cada tipo de parámetro se define mediante un objeto JSON:

Tipo

Objeto JSON

Notas

Template

{
"dataType": "string",
"defaultValue": "",
"description": "El nombre de la organización.",
“name”: “org_name”,
“obligatorio”: verdadero,
“type”: “TEMPLATE”
}

Los parámetros de plantilla siempre son obligatorios, por lo que debes establecer required en true y omitir el valor en defaultValue.

El valor de description aparece en una ventana emergente cuando el usuario se desplaza sobre la URL en una página de SmartDocs.

Consulta

{
"dataType": "string",
"defaultValue": "",
"description": "La ubicación.",
"name": "w",
"obligatorio": verdadero,
"type": "QUERY"
}

Los parámetros de consulta obligatorios aún pueden especificar un defaultValue, pero, a menudo, no lo hacen.

Para los parámetros opcionales de consulta, establece required en false y especifica un valor en defaultValue.

Encabezado

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

Observa cómo puedes usar etiquetas HTML en la descripción.

Un parámetro de plantilla define una variable en la ruta de acceso del recurso. Por ejemplo, debes definir dos parámetros de plantilla en el recurso. Observa cómo cada definición de parámetro en el array de parámetros está separada por una coma:

[
 {
  "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"
 }
]

Luego, puedes usar los parámetros de la plantilla en la definición de la ruta de acceso del recurso, encerrada en "{}". Por ejemplo, configura la ruta de acceso de la siguiente manera:

/login/{org_name}/{developer_email}

En la página de la API de SmartDocs, el usuario debe editar la URL para especificar la parte de org_name y developer_email de la URL antes de poder enviar una solicitud.

Cómo definir un método

Define uno o más métodos para cada recurso. La definición del método especifica un verbo HTTP que se puede invocar en el recurso. Un recurso puede tener uno o varios métodos definidos.

Como parte de la definición del método, especifica los parámetros que usa el método, incluidos los parámetros de consulta y encabezado. Consulta la descripción anterior para obtener información sobre cómo agregar parámetros a un método.

En la siguiente imagen, se muestra una página de SmartDocs existente para la API Create Developer de Apigee con cada área de la página destacada con el valor correspondiente que estableciste cuando definiste un método:

En la siguiente imagen, se muestra la misma página, pero con la opción Descripción del cuerpo de la solicitud seleccionada:

Para definir un método, haz lo siguiente:

  1. Accede a tu portal como un usuario con privilegios de administrador o de creación de contenido.
  2. Selecciona Contenido > SmartDocs en el menú de administración de Drupal.
  3. En el modelo que deseas actualizar, en Operaciones, selecciona Revisiones de API para ver todas las revisiones de un modelo.
  4. Selecciona una revisión para editar.
  5. En la página de revisión, selecciona Add Method en el menú desplegable de uno de los recursos.
  6. En la página Edit Method, ingresa la siguiente información:
    • Display Name: Es el nombre de la API, que también se convierte en el título de la página de Drupal para la API.
    • Description: Describe la API.
    • Method Verb: El tipo de verbo HTTP.
    • Esquemas de seguridad: Especifica el modo de autenticación, si corresponde, para el método. Para obtener más información, consulta Cómo configurar el tipo de autenticación de SmartDocs.
    • Tipo de contenido: El tipo de contenido de la solicitud y la respuesta. Consulta la siguiente sección para configurar diferentes métodos de autenticación.
    • Parámetros: Es cualquier parámetro de consulta o encabezado para el método (opcional). Consulta la descripción anterior para agregar un parámetro a un recurso y obtener más información.
    • Documentación del cuerpo de la solicitud: (opcional) describe el cuerpo de la solicitud. Los métodos POST y PUT toman un cuerpo de solicitud. Puedes usar esta área para describirla. Si omites este valor, el vínculo Descripción en Cuerpo de la solicitud se omitirá de la página de SmartDocs generada.
    • Ejemplo de cuerpo de la solicitud: Opcional: Muestra un ejemplo de un cuerpo de solicitud, generalmente como un objeto JSON o XML. En el caso de los verbos POST y PUT, se pasa el ejemplo de cuerpo de la solicitud como parte de cada solicitud. Los usuarios de la página SmartDocs editan este ejemplo antes de enviar una solicitud a la API. Si omites este valor, el vínculo Valor en Cuerpo de la solicitud se omite de la página de SmartDocs que se genera.
    • Etiquetas: Un array de etiquetas asociadas con la API. SmartDocs usa etiquetas para agrupar las APIs similares. Por ejemplo, puedes aplicar la etiqueta "Estadísticas" a todas las APIs relacionadas con las estadísticas. Puedes agrupar las APIs de diferentes recursos en una sola etiqueta si todas usan la misma etiqueta.
  7. Selecciona Add Method. Se te redireccionará a la página del modelo. Ahora, puedes renderizar y publicar tu método.

Renderiza un modelo

Después de agregar APIs a un modelo, puedes renderizarlo. El procesamiento convierte la descripción del modelo de la API en nodos de Drupal. Cuando se complete el procesamiento, tendrás un solo nodo de Drupal para cada API, en el que cada nodo de Drupal corresponde a una página HTML.

Puedes elegir renderizar todo el modelo de una sola vez o seleccionar APIs individuales para la renderización.

Para renderizar un modelo, haz lo siguiente:

  1. Accede a tu portal como un usuario con privilegios de administrador o de creación de contenido.
  2. Selecciona Contenido > SmartDocs en el menú de administración de Drupal.
  3. En el modelo que deseas renderizar, selecciona Revisiones de API en Operaciones.
  4. Selecciona la revisión que quieras renderizar. Solo puedes renderizar nodos de una sola revisión del modelo.
  5. Selecciona los métodos que se renderizarán.
  6. Selecciona Render Nodes en el menú desplegable Update options.
  7. Haz clic en Actualizar.
  8. Aparecerá una pantalla de carga para ver el progreso de la renderización de tus nodos.
    Una vez que se hayan procesado los nodos, el ID del nodo de Drupal para cada API aparecerá en la columna Asociación de nodos del modelo. Haz clic en el vínculo de la columna Asociación de nodos para ver el nodo renderizado.

En lugar de seleccionar Render Nodes,también puedes seleccionar Render and publish nodes para procesar y publicar de inmediato las APIs como un nodo de Drupal.

Nodos de publicación

Los usuarios del portal no pueden ver un nodo hasta que se publique. De manera opcional, puedes publicar nodos durante el proceso de renderización. Si eliges no publicar los nodos, tendrás que publicarlos de forma manual después de que se complete el procesamiento.

Para publicar un nodo, sigue estos pasos:

  1. Accede a tu portal como un usuario con privilegios de administrador o de creación de contenido.
  2. Selecciona Contenido >SmartDocs en el menú de administración de Drupal.
  3. En el modelo que deseas publicar, selecciona Revisiones de API en Operaciones.
  4. Selecciona la revisión que desees publicar. Solo puedes publicar nodos desde una única revisión del modelo.
  5. Selecciona los métodos para la publicación.
  6. Selecciona los nodos de la revisión que deseas publicar.
  7. Selecciona Publicar nodos del menú desplegable Actualizar opciones.
  8. Haz clic en Actualizar.
  9. Para navegar al nodo, selecciona el ID del nodo en la columna Asociación de nodos.

De forma predeterminada, la URL de Drupal a un nodo de la API publicado tiene el siguiente formato: http://<drupalBasePath>/<internalName>/apis/<httpMethod>/<resourcePath>. Usa el siguiente procedimiento para controlar el formato de la URL:

  1. Accede a tu portal como un usuario con privilegios de administrador o de creación de contenido.
  2. Selecciona Configuración > Búsqueda y metadatos > Alias de URL > Patrones en el menú de administración de Drupal.
  3. En Patrón para todas las rutas de acceso de los métodos de SmartDocs, especifica cómo deseas generar la ruta.
  4. Selecciona Guardar configuración.

Debido al almacenamiento en caché en el portal, es posible que no veas las páginas de tu modelo inmediatamente después de publicarlas. Si es necesario, puedes borrar manualmente la caché HTML de SmartDocs con el siguiente procedimiento:

  1. Accede a tu portal como un usuario con privilegios de administrador o de creación de contenido.
  2. Selecciona Configuración > SmartDocs en el menú de administración de Drupal.
  3. Haz clic en Volver a compilar cachés de modelos de SmartDocs.

Anula la publicación de un nodo

Puedes anular la publicación de un nodo publicado en cualquier momento. Si anulas la publicación de un nodo, será invisible para los usuarios del portal.

Para anular la publicación de un nodo, sigue estos pasos:

  1. Accede a tu portal como un usuario con privilegios de administrador o de creación de contenido.
  2. Selecciona Contenido > SmartDocs en el menú de administración de Drupal.
  3. En Operaciones, selecciona Revisiones de API en el modelo que deseas anular.
  4. Selecciona la revisión del modelo del nodo que deseas anular.
  5. Selecciona los nodos de la revisión para anular la publicación.
  6. Selecciona Anular publicación de nodos en el menú desplegable Opciones de actualización.
  7. Haz clic en Actualizar.

Visualiza la revisión de un modelo

Para crear una revisión nueva de un modelo, importa un archivo WADL nuevo o una especificación de OpenAPI a un modelo existente, o bien crea una revisión nueva de forma manual. Después de crear la revisión nueva, puedes renderizar y publicar la revisión, lo que reemplaza los nodos de Drupal publicados actualmente.

Puedes procesar y publicar nodos desde varias revisiones al mismo tiempo. Esto significa que, si tienes cinco revisiones de un modelo, puedes publicar nodos desde cualquiera o todas las revisiones. Sin embargo, cuando se publica una API en un modelo igual a un nodo publicado de otro modelo, se anula la publicación de la versión anterior de la API y se reemplaza por la de la API publicada más recientemente.

Para ver la revisión de un modelo, haz lo siguiente:

  1. Accede a tu portal como un usuario con privilegios de administrador o de creación de contenido.
  2. Selecciona Contenido > SmartDocs en el menú de administración de Drupal.
  3. En el modelo que deseas actualizar, selecciona Revisiones de API en Operaciones.
  4. Selecciona la revisión del modelo que deseas ver.
  5. Renderiza y publica los nodos como se describió anteriormente.

Edita un nodo

Después de renderizar un nodo, puedes editarlo con el editor de Drupal. Por ejemplo, puedes editar el verbo HTTP y la descripción de una API, o bien agregar una consulta o un parámetro de encabezado nuevos a la API. Puedes editar los nodos creados a partir de un archivo WADL o una especificación de OpenAPI, o los nodos que se crearon de forma manual.

También puedes editar el archivo WADL original o la especificación de OpenAPI. Cuando termines de editar, importa el archivo WADL o la especificación de OpenAPI al modelo como una revisión nueva y, luego, procesa y publica los cambios como se describió anteriormente.

Para editar un nodo mediante el editor de Drupal, sigue estos pasos:

  1. Accede a tu portal como un usuario con privilegios de administrador o de creación de contenido.
  2. Navega hasta el nodo de Drupal correspondiente a la documentación de la API que deseas editar.
  3. Selecciona Edit para usar el editor de Drupal.
  4. Cuando termines de editar la información, selecciona Update Method.

Como alternativa, puedes editar el nodo desde el modelo de SmartDocs:

  1. Accede a tu portal como un usuario con privilegios de administrador o de creación de contenido.
  2. Selecciona Contenido > SmartDocs en el menú de administración de Drupal.
  3. En el modelo que deseas actualizar, selecciona Revisiones de API en Operaciones.
  4. Selecciona la revisión del modelo que deseas publicar.
  5. Selecciona Editar método en el menú desplegable Operaciones para el método que deseas editar.

Para borrar un nodo, sigue estos pasos:

  1. Accede a tu portal como un usuario con privilegios de administrador o de creación de contenido.
  2. Selecciona Contenido > SmartDocs en el menú de administración de Drupal.
  3. En el modelo que deseas actualizar, selecciona Revisiones de API en Operaciones.
  4. Selecciona la revisión del modelo que deseas publicar.
  5. Selecciona Borrar método en el menú desplegable Operaciones para el método.
    Precaución: Si borras el nodo, también se quitará la API del modelo. Si solo deseas anular la publicación de la API para que esté oculta para los usuarios del portal, pero no quieres borrarla del modelo, debes anular la publicación del nodo como se describió antes.

El portal tiene un informe integrado que muestra información sobre los nodos renderizados por un modelo de SmartDocs que ya no hacen referencia a métodos válidos del modelo. Para acceder al informe, selecciona Informes en el menú de Drupal y, luego, el informe llamado Estado del nodo de SmartDocs.

Importar y exportar un modelo

SmartDocs te permite exportar un modelo existente a un archivo. Por ejemplo, puedes definir un entorno de producción y uno de etapa de pruebas. Luego, realiza todas las ediciones de SmartDocs en el entorno de etapa de pruebas. Cuando estés listo para lanzar tus API, exporta el modelo de etapa de pruebas y, luego, impórtalo al modelo de producción.

Cuando importas un modelo, se crea una revisión nueva del modelo. SmartDocs intenta hacer coincidir las APIs existentes en el modelo con las APIs importadas. Si SmartDocs detecta una coincidencia, la importación actualizará el nodo de Drupal correspondiente a la API existente. Si SmartDocs no detecta una coincidencia, la importación creará un nodo de Drupal nuevo para la API.

Por ejemplo, tiene una API de POST que corresponde a un nodo de Drupal con un ID de 91. Luego, importas un modelo, y SmartDocs detecta una coincidencia entre una API de POST en el modelo importado con la API de POST existente. Cualquier actualización en la API de POST se actualizará en el nodo de Drupal 91. Si SmartDocs no detecta una coincidencia, creará un nodo de Drupal nuevo con un ID nuevo.

Drupal realiza la coincidencia usando las siguientes características de la API:

  • internalName: Es el nombre del modelo interno.
  • httpMethod: El método HTTP de la API, como GET, PUT, POST o DELETE.
  • resourcePath: La ruta de acceso del recurso.
  • query params: Cualquier parámetro de consulta que usa la API.

Si las cuatro características de una API importada coinciden con una API existente en el modelo, SmartDocs actualiza el nodo de Drupal existente.

El modelo exportado está representado por un solo objeto JSON con entradas para recursos y métodos. Eso significa que puedes editar el modelo exportado para modificar un recurso o método y, luego, volver a importarlo. Si editas el objeto JSON, no modifiques los siguientes campos:

  • revisionNumber
  • createdTime
  • modifiedTime
  • apiRevisionId
  • resourceId

Para exportar un modelo, haz lo siguiente:

  1. Accede a tu portal como un usuario con privilegios de administrador o de creación de contenido.
  2. Selecciona Contenido > SmartDocs en el menú de administración de Drupal.
  3. Para el modelo que deseas exportar, selecciona Exportar en Operaciones.
  4. Selecciona el tipo de archivo de exportación como JSON de SmartDocs.
  5. Haz clic en Exportar.
  6. Se te indicará que guardes el archivo en el disco o que lo abras en un editor.

Para importar un modelo, haz lo siguiente:

  1. Accede a tu portal como un usuario con privilegios de administrador o de creación de contenido.
  2. Selecciona Contenido > SmartDocs en el menú de administración de Drupal.
  3. En el modelo que deseas importar, selecciona Importar en Operaciones.
  4. Selecciona JSON de SmartDocs en el menú desplegable Elegir formato.
  5. Selecciona Archivo o URL en el Tipo de carga:
    1. Si seleccionas Archivo, busca el archivo JSON.
    2. Si seleccionas URL, especifica la URL del archivo JSON de SmartDocs.
  6. Haz clic en Importar para importarlo al modelo.
  7. Se te redireccionará a la página de información del modelo, en la que ahora puedes renderizarlo. Ten en cuenta que la importación crea una revisión nueva del modelo.
  8. Renderiza y publica los nodos.

Cómo editar la plantilla de SmartDocs

La plantilla de SmartDocs define cómo aparecen tus nodos de Drupal en la pantalla. Cada modelo de SmartDocs puede usar la misma plantilla predeterminada o puedes personalizar manualmente la plantilla usada para un modelo individual.

La plantilla de SmartDocs incluye un archivo de plantilla codificado como un archivo .hbr de Handlebars, archivos CSS y archivos JavaScript. Con Handlebars, gran parte del contenido se basa en variables mediante expresiones de control incorporadas, como &123;&123;body}}. En un comentario en la parte superior del archivo, se proporciona una lista de las expresiones de Handlebar existentes. Si quieres obtener información sobre el uso de Handlebars para personalizar tus plantillas, consulta http://handlebarsjs.com.

En las siguientes secciones, se describe cómo subir un archivo de plantilla personalizado de SmartDocs para usarlo en todos los modelos nuevos o cuando importes nuevas API a un modelo existente, cómo restablecer el archivo de plantilla predeterminado original y cómo modificar la plantilla de SmartDocs para un modelo individual.

Cómo subir un archivo de plantilla personalizado de SmartDocs

Puedes subir un archivo de plantilla personalizado de SmartDocs, como un archivo .hbr de Handlebars, para usarlo como la plantilla predeterminada cuando crees modelos nuevos o importes nuevas APIs a un modelo existente.

Si quieres usar el archivo de plantilla de SmartDocs predeterminado como punto de partida para crear tu archivo de plantilla personalizado de SmartDocs, puedes descargar una copia desde: profiles/apigee/modules/custom/devconnect/smartdocs/templates/smartdocs.hbr.

Para subir un archivo de plantilla personalizado de SmartDocs, haz lo siguiente:

  1. Accede a tu portal como un usuario con privilegios de administrador o de creación de contenido.
  2. Selecciona Configuración > SmartDocs en el menú de administración de Drupal.
  3. Expande el área de Configuración avanzada de la página.
  4. En Subir plantilla de método personalizado, haz clic en Elegir archivo y navega hasta el archivo .hbr de Handlebars.
  5. Haz clic en Subir.
  6. Haga clic en Guardar configuración.

Restablece el archivo de plantilla predeterminado de SmartDocs

Puedes restablecer el archivo de plantilla predeterminado de SmartDocs. Una vez restablecido, se usará el archivo de plantilla predeterminado de SmartDocs cuando se creen modelos nuevos o se importen APIs nuevas a un modelo existente.

Para restablecer el archivo de plantilla predeterminado de SmartDocs:

  1. Accede a tu portal como un usuario con privilegios de administrador o de creación de contenido.
  2. Selecciona Configuración > SmartDocs en el menú de administración de Drupal.
  3. Expande el área de Configuración avanzada de la página.
  4. En Subir plantilla de método personalizado, haz clic en Quitar junto al archivo de plantilla de SmartDocs.
  5. Haga clic en Guardar configuración.

Modifica la plantilla de SmartDocs para un modelo individual

Puedes modificar la plantilla que se usa para un modelo individual.

Para modificar la plantilla de un modelo individual, sigue estos pasos:

  1. Accede a tu portal como un usuario con privilegios de administrador o de creación de contenido.
  2. Selecciona Contenido > SmartDocs en el menú de administración de Drupal.
  3. En el modelo que deseas editar, selecciona Configuración en Operaciones.
  4. En el área Plantilla de método, edita la plantilla según sea necesario.
  5. Haz clic en Guardar plantilla.
  6. Navega a un nodo de Drupal. Los cambios de tu plantilla deberían aparecer en la página.

Cómo configurar el tipo de autenticación de SmartDocs

Las APIs definidas en SmartDocs pueden ser abiertas, lo que significa que no se requieren credenciales de autenticación para acceder a ellas, o seguras. Para que la API sea segura, debes pasar las credenciales cuando realizas una llamada a la API.

Para una API segura, SmartDocs admite los siguientes tipos de autenticación:

  • Autenticación básica: Pasa credenciales de autenticación básicas como un par de nombre de usuario y contraseña. Si no especificas el uso de OAuth como el tipo de credencial, la API utilizará la autenticación básica de forma predeterminada.
  • OAuth 2.0: Un proveedor de servicios de terceros autentica las credenciales del usuario, garantiza que este tenga autorización para la API y, luego, emite un token de acceso. Cuando realizas una solicitud de SmartDocs a una API protegida, SmartDocs compila la solicitud y la envía al proveedor de servicios. Luego, el proveedor de servicios valida el token y se asegura de que no haya vencido.
  • Token personalizado: Pasa un valor de token como un encabezado o parámetro de consulta a cada solicitud.

Para cada tipo de autenticación, se crea un esquema de seguridad que defina las características de la autenticación. Por ejemplo, para la autenticación con un token personalizado, el esquema de seguridad define cómo se pasa el token (encabezado, parámetro de consulta, parámetro de cuerpo) y el nombre del token.

Un esquema de seguridad se asocia con una revisión específica de un modelo. Por lo tanto, si creas una revisión nueva de un modelo, debes volver a definir sus esquemas de seguridad

En un archivo WADL, especifica si una API requiere autenticación con la etiqueta <apigee:authentication> de Apigee, como se muestra a continuación:

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

Si la API está abierta, establece el atributo required en false.

Ten en cuenta que no puedes especificar el tipo de autenticación en el archivo WADL. Para ello, edita el nodo en Drupal. Para obtener más información sobre los archivos WADL, consulta la Referencia de WADL.

En la página de la API de Drupal, SmartDocs agrega el siguiente botón para permitir que los usuarios especifiquen sus credenciales de autenticación básicas:

Si editas el nodo para establecer el tipo de autenticación en OAuth, SmartDocs agregará el siguiente botón a la página:

Para el token personalizado, SmartDocs agrega:

Configuración de la autenticación básica

Si usas la autenticación básica con la API, solo tienes que especificar la etiqueta <apigee:authentication> en el archivo WADL que usas para crear el modelo.

Para aplicar la autenticación básica a los métodos creados a partir de una fuente que no sea un archivo WADL, haz lo siguiente:

  1. Accede a tu portal como un usuario con privilegios de administrador o de creación de contenido.
  2. Selecciona Contenido > SmartDocs en el menú de administración de Drupal.
  3. Para el modelo deseado, selecciona Revisiones de API en Operaciones.
  4. En la revisión del modelo que deseas editar, selecciona Configuración de seguridad en Operaciones.
  5. Selecciona Agregar esquema de seguridad.
  6. Especifica el name del esquema de seguridad.
  7. En Tipo, selecciona Básico.
  8. Selecciona Enviar.
  9. Para cada método en el modelo, edítalo a fin de establecer su Esquema de seguridad como tu esquema básico.
    1. Selecciona Contenido > SmartDocs en el menú de administración de Drupal.
    2. Para el modelo deseado, selecciona Revisiones de API en Operaciones.
    3. En la revisión del modelo que deseas editar, selecciona Detalles de la revisión en Operaciones.
    4. Selecciona Edit Method en la API que desees editar.
    5. Selecciona el Esquema de seguridad para la API.
    6. Guarda la API.

Cómo configurar la autenticación de OAuth 2.0

Puedes configurar un modelo para usar OAuth 2.0 en SmartDocs, en lugar del valor predeterminado de la autenticación básica. Puedes configurar OAuth en dos ubicaciones:

  1. Crea un esquema de seguridad para cada revisión de un modelo en Configuración de seguridad.
  2. Especifica el ID de cliente y el Secreto de cliente para todas las revisiones del modelo en Configuración del modelo.

Para habilitar OAuth, haz lo siguiente:

  1. Accede a tu portal como un usuario con privilegios de administrador o de creación de contenido.
  2. Selecciona Contenido > SmartDocs en el menú de administración de Drupal.
  3. Para el modelo deseado, selecciona Revisiones de API en Operaciones.
  4. Para la revisión del modelo que deseas editar, selecciona Configuración de seguridad en Operaciones.
  5. Selecciona Agregar esquema de seguridad.
  6. Especifica el name del esquema de seguridad.
  7. En Tipo, selecciona OAuth 2.0.
  8. Configura el Tipo de otorgamiento.
  9. Ingresa los valores en los campos URL de autorización. La URL de autorización se usa para obtener el token de acceso.
  10. Configura el Verbo de autorización como GET o POST.
  11. Ingresa la URL del token de acceso. La URL del token de acceso es la URL que se usa para intercambiar el token de solicitud por un token de acceso.
  12. Ingresa el nombre del parámetro del token de acceso.
  13. Usa In para especificar cómo pasar el token: Header, Query o Body.
  14. Configura los permisos de OAuth.
  15. Selecciona Enviar.
  16. Selecciona Contenido > SmartDocs en el menú de administración de Drupal.
  17. Para el modelo, selecciona Configuración en el menú desplegable Operaciones.
  18. Ingresa los valores en ID de cliente y Secreto del cliente.
  19. Selecciona Guardar configuración de autenticación de plantillas.
  20. En cada método del modelo, edítalo para configurar su Esquema de seguridad con el esquema de seguridad de OAuth.
    1. Selecciona Contenido > SmartDocs en el menú de administración de Drupal.
    2. Para el modelo deseado, selecciona Revisiones de API en Operaciones.
    3. En la revisión del modelo que deseas editar, selecciona Detalles de la revisión en Operaciones.
    4. Selecciona Edit Method en la API que desees editar.
    5. Selecciona el Esquema de seguridad para la API.
    6. Guarda la API.

Configura la autenticación con token personalizado

Puedes configurar un modelo para usar la autenticación con token personalizado.

Para habilitar los tokens personalizados, haz lo siguiente:

  1. Accede a tu portal como un usuario con privilegios de administrador o de creación de contenido.
  2. Selecciona Contenido > SmartDocs en el menú de administración de Drupal.
  3. Para el modelo deseado, selecciona Revisiones de API en Operaciones.
  4. En la revisión del modelo que deseas editar, selecciona Configuración de seguridad en Operaciones.
  5. Selecciona Agregar esquema de seguridad.
  6. Especifica el name del esquema de seguridad.
  7. En Tipo, selecciona Clave de API.
  8. Configura el Param Name que contiene el token.
  9. Usa In para especificar cómo pasar el token: Header, Query o Body.
  10. Selecciona Enviar.
  11. Para cada método en el modelo, edítalo a fin de configurar su Esquema de seguridad con el esquema de tokens.
    1. Selecciona Contenido > SmartDocs en el menú de administración de Drupal.
    2. Para el modelo deseado, selecciona Revisiones de API en Operaciones.
    3. En la revisión del modelo que deseas editar, selecciona Detalles de la revisión en Operaciones.
    4. Selecciona Edit Method en la API que desees editar.
    5. Selecciona el Esquema de seguridad para la API.
    6. Guarda la API.

Borra un modelo

Cuando borras un modelo (Contenido > SmartDocs, Borrar en el campo Operaciones de Drupal), el modelo se borra de tu organización de Edge. Esto significa que si otros portales hacen referencia al modelo, este ya no estará disponible. Para obtener más información, consulta Acerca de las plantillas y los modelos de SmartDoc.