Cómo usar SmartDocs para documentar las API

Estás viendo la documentación de Apigee Edge.
Ve a 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 documentación de API completamente interactiva. Con la documentación interactiva, los usuarios del portal pueden hacer lo siguiente:

  • Obtén información sobre tus APIs
  • Envía una solicitud en tiempo real a tu API
  • Visualiza una respuesta en vivo que muestra la API

Cuando creas una documentación interactiva en tus APIs, permites que el usuario del portal aprender, probar y evaluar tus APIs.

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

Ejemplo del portal de SmartDocs

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

En la barra de navegación superior, haz clic en APIs en la página principal del portal para desarrolladores para para ver la página de 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 OpenAPI de destino ficticio Especificación, mocktarget.yaml. Para obtener más información, consulte 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 de la tienda de mascotas clásica.

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 afirmación de la API. Los SmartDocs para este recurso son se muestran:
  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 cURL. para ver la llamada cURL correspondiente.

Cómo documentar tus APIs con SmartDocs

SmartDocs representa tus APIs a través de un modelo, en el que el modelo contiene todas las información sobre tus APIs. El portal extrae información sobre tus APIs del modelo para renderizar las páginas de documentación en el portal como nodos de Drupal, en los que cada nodo de Drupal se a una página de documentación en el portal.

Estos son los pasos generales que debes seguir para usar SmartDocs:

  1. Configura el módulo de Drupal SmartDocs en el portal.
  2. Crea un modelo de SmartDocs.
  3. Agregar APIs al modelo desde un archivo WADL, OpenAPI (anteriormente Swagger) específica, 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 en tu API admite un POST y PUT, SmartDocs crea un nodo de Drupal independiente para los métodos POST y PUT.
  5. Publica los nodos de Drupal. Una vez publicado, los usuarios de tu portal podrán ver y interactuar con tu API.
  6. Edita los nodos de Drupal antes o después de publicarlos. Puedes editar los nodos de Drupal usando el editor de Drupal o editando el archivo WADL original, o Especificación de OpenAPI. Cuando termines de editar el archivo WADL o la especificación de OpenAPI, importa de nuevo en el modelo como una revisión nueva y, luego, renderizar y publicar los cambios.
  7. Habilita TLS. Como SmartDocs puede enviar credenciales de autenticación a tus backend como parte de hacer una solicitud a tus APIs, debes habilitar TLS en tu portal para garantizar 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 ir en vivo con tu portal, debes obtener tu propio certificado TLS y habilitar TLS. Para obtener más información, consulta El uso de TLS en portal.

Acerca de los modelos y las plantillas de SmartDoc

Cuando creas un modelo en el portal, este se almacena en 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. Tu portal, por otro lado, Renderiza el modelo en HTML y proporciona una interfaz de edición para el modelo. Cualquier actualización de la API del portal se envían automáticamente al modelo fuente.

Almacenados en la organización

Almacenado en Drupal

modelos

templates

Nodos de Drupal con funcionalidad de edición

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

Las plantillas controlan el aspecto de tus SmartDocs y esas plantillas (controladas por Handlebars y archivos CSS) se almacenan con cada instancia del portal. De modo que, en teoría, cada portal usar una plantilla única para cada modelo. Sin embargo, una de las ventajas del framework de renderización es que una plantilla predeterminada (ya sea la predeterminada de Apigee o una que tú proporciones) se convierte automáticamente que se aplican a cada modelo.

En el siguiente diagrama, se muestra la relación entre los modelos y los portales. Las flechas verdes muestran y 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

Configuración del módulo SmartDocs

Apigee implementó SmartDocs como un módulo personalizado de Drupal. Usa el siguiente procedimiento para configurar el módulo 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 Módulos en el menú de administración de Drupal. La lista de todas de los módulos de Drupal instalados.
  3. Habilita el módulo SmartDocs.
  4. Guarde la configuración.
  5. Selecciona Módulos en el menú de administración de Drupal.
  6. Selecciona SmartDocs -> Permisos y asegúrate de que "Realizar la administración para el módulo SmartDocs" de "Administrador" de que el rol esté habilitado.
  7. Selecciona Configuración > Portal para desarrolladores en la administración de Drupal .
  8. Establece el Tiempo de espera de la conexión y Tiempo de espera de la solicitud en 16. segundos.
  9. Guarde la configuración.
  10. Establece la configuración de la URL:
    1. Selecciona Configuración > Búsqueda y metadatos > Alias de URL > Settings en el menú de Drupal.
    2. Establece la Longitud máxima del alias y el Componente máximo length en 255.
    3. Expande Puntuación.
    4. Para la Llave de apertura ({) y la Llave de cierre (}), selecciona Sin acción (no reemplazar).
    5. Haga clic en Guardar configuración.
  11. Si tu portal para desarrolladores se expone a usuarios en una red interna sin acceso a o si un subconjunto de tus APIs está en una red privada, configura la API de SmartDocs proxy, como se muestra a continuación:
    1. Selecciona Configuración > SmartDocs en Drupal Administration .
    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 necesario 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 una sola un modelo de responsabilidad compartida.

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

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

Donde:

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

Por ejemplo, si especificas el nombre interno como “mimodelo”, entonces la URL del Nodo de Drupal para una solicitud GET a un recurso llamado "/books" es:

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

Para crear un modelo

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

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

Después de crear el modelo, se te redireccionará a la página correspondiente. A partir de ahí, puedes usar el menú desplegable Operaciones bx para:

  • Importa un archivo WADL que describa tu API o especifica la URL de una OpenAPI La especificación que describe tu API.
  • Agregar revisión al modelo
  • Modifica la Configuración del modelo, incluidas las hojas de estilo utilizadas por un modelo de responsabilidad compartida.
  • 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 contenga la definición de la API
  • Importa 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 lo crea primero exportar un modelo existente, editar el archivo y, luego, importar las actualizaciones. Para obtener más información, consulta “Exporta e importa un modelo” a continuación.

Video: Mira un breve video para aprender a agregar APIs a un modelo de SmartDocs importar una especificación de OpenAPI.

Importa un WADL

Después de crear un modelo correctamente, importa un archivo WADL que describa tu API. Cada cada vez que importas un archivo WADL, automáticamente creas una nueva revisión del modelo.

  1. Accede a tu portal como un usuario con privilegios de administrador o de creación de contenido.
  2. Selecciona Contenido > SmartDocs en Drupal de administración.
  3. Selecciona el modelo que deseas actualizar.
  4. En Operaciones, selecciona Importar.
  5. Selecciona WADL en el menú desplegable Choose Format en la Página de importación de SmartDocs
  6. Selecciona File o URL en la sección Upload Type en el menú desplegable.
    1. Si seleccionas File, navega hasta 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, donde ahora puedes renderizar el un modelo de responsabilidad compartida.

Importa una OpenAPI Especificación

Después de crear un modelo con éxito, puedes importar una OpenAPI (anteriormente Swagger) Especificación. Edge es compatible con las versiones 1.2 y 2.0 de OpenAPI.

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

Para importar una especificación de OpenAPI:

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

Creación manual de recursos y métodos

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

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 ruta base única 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 como:

    https://myCompany.com/v1

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

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

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

Como regla general:

  • Crea un modelo de SmartDocs diferente para cada ruta base única en tu API.
  • Definir un recurso de SmartDocs diferente para cada recurso único en tu API
  • Definir 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 un puedes agregar el recurso. Si el modelo es nuevo y no tiene revisiones, crea uno nuevo. a los cambios en el software.

Para crear una nueva 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. Seleccionar Contenido > SmartDocs en el menú de administración de Drupal.
  3. En el modelo que quieres actualizar, selecciona Agregar revisión. en Operaciones.
  4. En la página Agregar revisión de API, ingresa la siguiente información:
    • Nombre visible: Es el nombre de la revisión tal como aparece en la portal.
    • ID de versión: Es un identificador corto para la revisión.
    • Descripción: Una descripción de la revisión.
    • URL base: Es la URL base de todas las APIs en la revisión del modelo. R puede usar diferentes URL base para cada revisión. Por ejemplo, puedes incluir una versión en la URL base. Para la primera revisión de modelo, la URL base es:
      https://myCompany.com/v1
      Para la próxima revisión, la URL base podría ser la siguiente:
      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 se define un recurso, se especifica la ruta 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. Seleccionar Contenido > SmartDocs en el menú de administración de Drupal.
  3. Para el modelo que deseas actualizar, en Operaciones, selecciona API. Revisiones para ver todas las revisiones de un modelo.
  4. Selecciona una revisión para editar.
  5. En la página de revisión, selecciona 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 al 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 (Description): 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 Add Resource. Se te redireccionará a la página del modelo. Ahora puedes definir métodos en el recurso.

De forma opcional, puedes agregar parámetros al recurso, como plantillas, consultas y encabezados parámetros. Cualquier método definido en ese recurso hereda todos los parámetros de recursos. Por lo tanto, si defines un parámetro de consulta en el recurso, todos los métodos agregados a ese recurso debe admitir ese parámetro de consulta.

Como alternativa, puedes definir parámetros en un método. Por ejemplo, un método POST podría admitir parámetros de consulta que no son compatibles con un método DELETE Por lo tanto, agrega cualquier parámetro específicas 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 el API de Apigee Approve or Redirect Developer App con cada tipo de parámetro destacado:

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

Tipo

Objeto JSON

Notas

Plantilla

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

Los parámetros de plantilla siempre son obligatorios, así que establece required en true y omite el valor para defaultValue.

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

Consulta

{
"dataType": "cadena",
“defaultValue”: “”,
"description": "La ubicación.",
"name": "w",
"required": 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 de consulta opcionales, establece required en false y especifica un valor para defaultValue.

Encabezado

{
"dataType": "cadena",
“defaultValue”: “application/json”,
"description": "Especificar como <code>application/json</code>".",
"name": "Tipo de contenido",
"required": verdadero,
"type": "ENCABEZADO"
}

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

Un parámetro de plantilla define una variable en la ruta del recurso. Por ejemplo, puedes 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á separado 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"
 }
]

Puedes usar los parámetros de la plantilla en la definición de la ruta de acceso del recurso, dentro de “{}”. 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 las partes org_name y developer_email de la URL antes pueden enviar una solicitud.

Define 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 pueden invocar en el recurso. Un recurso puede tener un solo método definido en él. múltiples métodos.

Como parte de la definición del método, especifica los parámetros que usa, incluidas las consultas y parámetros de 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 al definir método:

La siguiente imagen muestra la misma página, pero con la 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. Seleccionar Contenido > SmartDocs en el menú de administración de Drupal.
  3. Para el modelo que deseas actualizar, en Operaciones, selecciona API. Revisiones para ver todas las revisiones de un modelo.
  4. Selecciona una revisión para editar.
  5. En la página de revisión, selecciona Agregar método en el menú desplegable de uno de los recursos.
  6. En la página Editar método, ingresa la siguiente información:
    • Nombre visible: el nombre de la API, que también se convierte en el título de Página de Drupal para la API.
    • Description (Descripción): Describe la API.
    • Método Verb: Es el tipo de verbo HTTP.
    • Esquemas de seguridad: Especifica el modo de autenticación, si lo hay, para el . Para obtener más información, consulte Cómo configurar la autenticación de SmartDocs del tipo de fila.
    • Content Type: Es el tipo de contenido de la solicitud y la respuesta. Consulta la a continuación sobre cómo configurar distintos 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: Describe el cuerpo de la solicitud (opcional). PUBLICAR y los métodos PUT toman un cuerpo de solicitud. Puedes usar esta área para describirla. Si omites esto valor, se omite el vínculo Description en Cuerpo de la solicitud. desde la página de SmartDocs generada.
    • Ejemplo de cuerpo de la solicitud: Muestra un ejemplo de cuerpo de la solicitud (opcional). generalmente como un objeto JSON o XML. Para los verbos POST y PUT, el campo Cuerpo de la solicitud Example como parte de cada solicitud. Los usuarios de la página SmartDocs editan esto ejemplo antes de que envíen una solicitud a la API. Si omites este valor, El vínculo Value en Cuerpo de la solicitud se omite desde la página de SmartDocs generada.
    • Etiquetas: Es un array de etiquetas asociadas con la API. SmartDocs usa etiquetas para y agrupar APIs similares. Por ejemplo, puedes aplicar la etiqueta "Estadísticas" a todas las APIs sobre estadísticas. Puedes agrupar las APIs de diferentes recursos en una sola etiqueta. si no 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 renderizar el modelo. La renderización convierte las entradas del modelo descripción de la API en nodos de Drupal. Cuando se complete la renderización, tendrás un solo Drupal para cada API, en la que cada nodo de Drupal corresponde a una página HTML.

Puedes elegir renderizar todo el modelo de una vez o seleccionar APIs individuales para y procesamiento.

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. Seleccionar Contenido > SmartDocs en el menú de administración de Drupal.
  3. Para el modelo que deseas renderizar, selecciona Revisiones de la API en Operaciones.
  4. Selecciona la revisión que deseas renderizar. Solo puedes renderizar nodos de una sola revisión de el modelo.
  5. Selecciona los métodos que quieras renderizar.
  6. Selecciona Nodos de renderización en Actualizar. Menú desplegable options.
  7. Haz clic en Actualizar.
  8. Aparecerá una pantalla de carga para ver el progreso de la renderización de los nodos.
    Una vez que se hayan renderizado los nodos, el ID del nodo de Drupal para cada API aparecerá en el La columna Asociación de nodos del modelo. Haz clic en el vínculo en el Nodo Association para ver el nodo renderizado.

En lugar de seleccionar Nodos de renderización,puedes seleccionar Renderizar y publicar nodos para renderizar y publicar de inmediato las APIs como un nodo de Drupal.

Publicación de nodos

Los usuarios del portal no podrán ver los nodos hasta que se publiquen. De manera opcional, puedes optar por publican 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, haz lo siguiente:

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

De forma predeterminada, la URL de Drupal a un nodo de 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 los métodos de SmartDocs, especifica cómo deseas hacerlo. generar la ruta de acceso.
  4. Selecciona Guardar configuración.

Debido al almacenamiento en caché en el portal, es posible que no veas las páginas de modelos que aparecen de inmediato. luego de publicarlas. Si fuera necesario, puede 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 la 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. Anular la publicación de un nodo lo hace invisible para usuarios del portal.

Para anular la publicación de un nodo, haz lo siguiente:

  1. Accede a tu portal como un usuario con privilegios de administrador o de creación de contenido.
  2. Seleccionar Contenido > SmartDocs en el menú de administración de Drupal.
  3. Selecciona Revisiones de la API en el modelo del que deseas anular la publicación. Operaciones.
  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 los nodos para anular la publicación en Actualizar Menú desplegable options.
  7. Haz clic en Actualizar.

Visualiza la revisión de un modelo

Crea una revisión nueva de un modelo mediante la importación de un archivo WADL o una especificación de OpenAPI nuevos en un modelo existente o creando manualmente una nueva revisión. Después de crear la revisión nueva, Puedes renderizar y publicar la revisión, lo que reemplazará los nodos de Drupal publicados actualmente.

Puedes renderizar y publicar nodos de varias revisiones al mismo tiempo. Es decir, si tienes cinco revisiones de un modelo, puedes publicar nodos de una revisión o de todas. Sin embargo, la publicación una API en un modelo que es igual a un nodo publicado de otro modelo anula la publicación del de la API y la reemplaza con la de la versión publicada más recientemente en la API de Cloud.

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. Seleccionar Contenido > SmartDocs en el menú de administración de Drupal.
  3. En el modelo que deseas actualizar, selecciona Revisiones de la API en Operaciones.
  4. Selecciona la revisión del modelo que deseas ver.
  5. Renderiza y publica los nodos como se describió anteriormente.

Cómo editar 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 agregar una nueva consulta o un parámetro de encabezado a la API. Tú editar nodos creados a partir de un archivo WADL o una especificación de OpenAPI, o nodos creados manualmente.

También puedes editar el archivo WADL original o la especificación de OpenAPI. Cuando hayas terminado con importarás el archivo WADL o la especificación de OpenAPI al modelo como una revisión nueva Luego, procesa y publica tus cambios como se describió anteriormente.

Para editar un nodo con el editor de Drupal, haz lo siguiente:

  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 Editar para usar el editor de Drupal.
  4. Cuando se completen tus ediciones, selecciona Método de actualización.

También 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 la API en Operaciones.
  4. Selecciona la revisión del modelo que deseas publicar.
  5. Selecciona Editar método (Edit method) en el menú desplegable Operaciones (Operations) para la método que quieres editar.

Para borrar un nodo, 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 la API en Operaciones.
  4. Selecciona la revisión del modelo que deseas publicar.
  5. Selecciona Borrar método en en el menú desplegable Operaciones para el método.
    Precaución: Borrar el nodo también quita la API del modelo. Si solo quiere anular la publicación de la API para ocultarla de los usuarios del portal, pero no quiere borrarla del modelo, debes anular la publicación del nodo como se describió anteriormente.

El portal tiene un informe integrado que muestra información sobre cualquier nodo renderizado por una SmartDocs que ya no hacen referencia a métodos válidos del modelo. Para acceder al informe, sigue estos pasos: selecciona Informes en el menú de Drupal y, luego, elige el informe llamada Estado del nodo de SmartDocs.

Importar y exportar un modelo

SmartDocs te permite exportar un modelo existente a un archivo. Por ejemplo, puedes definir y un entorno de etapa de pruebas. Realizas todos los cambios de SmartDocs en la etapa de pruebas en un entorno de nube. Cuando tengas todo listo para lanzar tus APIs, exporta el modelo de etapa de pruebas y, luego, impórtalo. en el modelo de producción.

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

Por ejemplo, tienes una API de POST que corresponde a un nodo de Drupal con un ID de 91. Luego, importar un modelo, y SmartDocs detectará una coincidencia entre una API de POST en el modelo importado y el existente API de POST. Cualquier actualización de la API de POST actualiza el nodo 91 de Drupal. Si SmartDocs no detecta un correspondiente, se crea un nodo de Drupal nuevo con un ID nuevo.

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

  • internalName: El nombre del modelo interno
  • httpMethod: El método HTTP de la API, como GET, PUT, POST o BORRAR
  • resourcePath: La ruta de acceso al 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, entonces SmartDocs actualiza el nodo de Drupal existente.

El modelo exportado está representado por un único objeto JSON con entradas de recursos y . Esto significa que puedes editar el modelo exportado para modificar un recurso o método y, luego, volver a importar el modelo. 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. Seleccionar Contenido > SmartDocs en el menú de administración de Drupal.
  3. En el modelo que deseas exportar, selecciona Exportar. Operaciones.
  4. Selecciona el tipo de archivo de exportación SmartDocs JSON.
  5. Haz clic en Exportar.
  6. Se te solicitará 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. Seleccionar Contenido > SmartDocs en el menú de administración de Drupal.
  3. Selecciona Importar en el modelo que desees importar. 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 File, navega hasta 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, donde ahora puedes renderizar el un modelo de responsabilidad compartida. Ten en cuenta que la importación crea una revisión nueva del modelo.
  8. Renderiza y publica los nodos.

Edita la plantilla de SmartDocs

La plantilla de SmartDocs define cómo aparecen tus nodos de Drupal en la pantalla. Cada SmartDocs puede usar la misma plantilla predeterminada o personalizar manualmente la plantilla que se usa modelo individual.

La plantilla de SmartDocs incluye un archivo de plantilla codificado como archivo .hbr de Handlebars, archivos CSS, y archivos JavaScript. Con los Handlebars, la mayor parte del contenido depende de las variables usando modelos manillares, como &123;&123;body}}. Una lista de los existentes Las expresiones de Handlebar se proporcionan en un comentario en la parte superior del archivo. Para obtener información sobre usando Handlebars para personalizar tus plantillas, consulta http://handlebarsjs.com.

En las siguientes secciones, se describe cómo subir un archivo de plantilla de SmartDocs personalizado para que lo usen todos para modelos nuevos o cuando importas APIs nuevas a un modelo existente, cómo restablecer la el archivo de plantilla original predeterminado de SmartDocs y cómo modificar la plantilla de SmartDocs para un modelo individual.

Cómo subir una foto personalizada Archivo de plantilla de SmartDocs

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

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

Para subir un archivo de plantilla de SmartDocs personalizado:

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

El restablecimiento del archivo de plantilla predeterminado de SmartDocs

Puedes restablecer el archivo de plantilla predeterminado de SmartDocs. Cuando los restablezcas, la app predeterminada de SmartDocs archivo de plantilla se usará cuando se creen modelos nuevos o se importen nuevas APIs a una un modelo de responsabilidad compartida.

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 Drupal de administración.
  3. Expande el área Configuración avanzada de la página.
  4. En Subir plantilla de método personalizada, haz clic en Quitar junto al archivo un archivo de plantilla personalizado de SmartDocs.
  5. Haga clic en Guardar configuración.

Modificando 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, haz lo siguiente:

  1. Accede a tu portal como un usuario con privilegios de administrador o de creación de contenido.
  2. Seleccionar Contenido > SmartDocs en el menú de administración de Drupal.
  3. Selecciona Configuración en el modelo que quieras editar. Operaciones.
  4. En el área Plantilla de método, edítala según sea necesario.
  5. Haz clic en Guardar plantilla.
  6. Navega hasta un nodo de Drupal. Deberías ver los cambios de tu plantilla en la página.

Cómo configurar Tipo de autenticación de SmartDocs

Las APIs definidas en SmartDocs pueden estar abiertas, lo que significa que no hay credenciales necesario para acceder a ellos o protegerlos. Una API segura requiere que pases credenciales cuando realices una llamada a la API.

Para que la API sea segura, SmartDocs admite los siguientes tipos de autenticación:

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

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

Un esquema de seguridad se asocia con una revisión específica de un modelo. Por lo tanto, si creas una nueva revisión de un modelo, se deben redefinir los esquemas de seguridad para esa revisión

En un archivo WADL, se especifica si una API requiere autenticación con la etiqueta &lt;apigee:authentication&gt; 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. Lo haces de la siguiente manera: y editarás el nodo en Drupal. Para obtener más información sobre los archivos WADL, consulta WADL Referencia.

En la página de la API en Drupal, SmartDocs agrega el siguiente botón para permitir a los usuarios especificar su 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 los tokens personalizados, SmartDocs agrega lo siguiente:

Configurando autenticación básica

Si usas la autenticación básica con tu API, solo debes especificar la etiqueta &lt;apigee:authentication&gt; en el 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 la API en Operaciones.
  4. Para la revisión del modelo que deseas editar, selecciona Seguridad Settings, en Operations.
  5. Selecciona Agregar esquema de seguridad.
  6. Especifica el name del esquema de seguridad.
  7. En Tipo, selecciona Básico.
  8. Selecciona Enviar.
  9. Edítalo para cada método del modelo para establecer su Esquema de seguridad a tu esquema básico.
    1. Selecciona Contenido > SmartDocs en el menú de administración de Drupal.
    2. Para el modelo deseado, selecciona Revisiones de la API en Operaciones.
    3. Para la revisión del modelo que deseas editar, selecciona Revisión. Detalles en Operaciones.
    4. Selecciona Edit Method para la API que deseas editar.
    5. Selecciona el Esquema de seguridad para la API.
    6. Guarda la API.

Configurando Autenticación de OAuth 2.0

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

  1. Crear un esquema de seguridad para cada revisión de un modelo en Seguridad Configuración de la revisión.
  2. Especifica el ID de cliente y el secreto del cliente para todas las revisiones del modelo en La configuración del modelo.

Sigue estos pasos para habilitar OAuth:

  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 la API en Operaciones.
  4. Para la revisión del modelo que quieras editar, selecciona Configuración de seguridad en Operaciones.
  5. Selecciona Agregar esquema de seguridad.
  6. Especifica el name del esquema de seguridad.
  7. Selecciona OAuth 2.0 como el Tipo.
  8. Establece el Tipo de otorgamiento.
  9. Ingresa los valores en los campos Authorization URL. La autorización La URL se usa para obtener el token de acceso.
  10. Establece 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 uno de acceso.
  12. Ingresa el nombre del parámetro de 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 Operaciones. en el menú desplegable.
  18. Ingresa los valores en el ID de cliente y en el cliente. Secreto.
  19. Selecciona Guardar configuración de autenticación de plantillas.
  20. Edítalo para cada método del modelo para establecer su Esquema de seguridad a tu esquema de seguridad OAuth.
    1. Selecciona Contenido > SmartDocs en el menú de administración de Drupal.
    2. Para el modelo deseado, selecciona Revisiones de la API en Operaciones.
    3. Para la revisión del modelo que deseas editar, selecciona Revisión. Detalles en Operaciones.
    4. Selecciona Edit Method para la API que deseas 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 que use la autenticación de token personalizado.

Sigue estos pasos para habilitar los tokens personalizados:

  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 la API en Operaciones.
  4. Para la revisión del modelo que deseas editar, selecciona Seguridad Settings, en Operations.
  5. Selecciona Agregar esquema de seguridad.
  6. Especifica el name del esquema de seguridad.
  7. Selecciona Apikey como el Tipo.
  8. Establece el Nombre Param que contiene el token.
  9. Usa In para especificar cómo pasar el token: Encabezado, Consulta, o Body.
  10. Selecciona Enviar.
  11. Edítalo para cada método del modelo para establecer su Esquema de seguridad a tu esquema de tokens.
    1. Selecciona Contenido > SmartDocs en el menú de administración de Drupal.
    2. Para el modelo deseado, selecciona Revisiones de la API en Operaciones.
    3. Para la revisión del modelo que deseas editar, selecciona Revisión. Detalles en Operaciones.
    4. Selecciona Edit Method para la API que deseas 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 en Drupal), se borrará el modelo de la organización de Edge. Eso significa que que otros portales hacen referencia al modelo, este ya no está disponible. Para obtener más información, consulte Acerca de los modelos y las plantillas de SmartDoc.