Actualizar SmartDocs

A partir del 21 de marzo de 2022, el Portal de Cloud Endpoints quedó obsoleto. El Portal de Cloud Endpoints dejará de estar disponible después del 21 de marzo de 2023. El tráfico de API administrado por Cloud Endpoints no se ve afectado por este cambio. Para obtener más información, consulta Bajas de funciones.

Antes de proporcionar la URL del portal a los usuarios de la API, debes asegurarte de que la documentación de referencia de la API de SmartDocs sea correcta y de que la API se comporte según lo esperado. Mientras revisas la documentación de referencia y la prueba que se generaron, es posible que veas algo que deseas cambiar.

En esta página, se describe lo siguiente:

• La documentación de referencia de la API de SmartDocs
• Cómo usa SmartDocs los campos del archivo openapi.json que crea Cloud Endpoints Frameworks para generar SmartDocs.
• Cómo volver a generar SmartDocs. Para cada tarea, se proveen las funciones mínimas de Identity and Access Management que se requieren para poder cumplirla. Si deseas obtener más información sobre los permisos de IAM, consulta los siguientes vínculos:
  • Comprende las funciones
  • Cómo otorgar, cambiar y revocar el acceso a los recursos
  • Crea y administra funciones personalizadas

Requisitos previos

En esta página, se da por sentado que ya creaste tu portal.

Acerca de la documentación de referencia de la API de SmartDocs

Cuando agregas la administración de API como se describe en los siguientes vínculos:

• Java: agregar administración de API
• Python: agrega administración de API

Esto causará que Endpoints Frameworks cree un documento de OpenAPI para tu API. Cada vez que implementes el documento de OpenAPI en el servicio de Endpoints, SmartDocs generará documentación de referencia de la API para tu portal. La IU de SmartDocs se basa en Angular Material, una biblioteca avanzada de componentes de IU. Los desarrolladores pueden revisar tu documentación de referencia de la API de SmartDocs y usar el widget Prueba esta API para interactuar con tu API sin salir de su documentación.

Acerca de los campos que se utilizan para generar SmartDocs

Cuando agregas la administración de API como se describe en los siguientes vínculos:

• Java: agregar administración de API
• Python: agrega administración de API

Endpoints Frameworks crea un documento de OpenAPI en formato JSON para tu API. Cuando implementas el documento de OpenAPI (con gcloud endpoints services deploy), SmartDocs genera una documentación de referencia de la API actualizada para tu portal basada en el documento de OpenAPI que Endpoints Frameworks creó.

Endpoints Frameworks no incluye descripciones en el documento de OpenAPI que crea para tu API. Antes de proporcionar la URL de tu portal a los usuarios de la API, recomendamos que agregues descripciones a la API, métodos y parámetros en el documento de OpenAPI.

Si aún no te familiarizaste con OpenAPI, puedes comenzar con el sitio web Estructura básica de Swagger, que proporciona un documento de OpenAPI de muestra y explica brevemente cada sección del archivo. Para obtener más información, consulta la Especificación de OpenAPI.

Como se describe en la sección de metadatos, el valor para el campo description puede contener varias líneas y es compatible con GitHub Flavored Markdown.

Para ayudar a tus usuarios a comprender cómo usar los métodos en la API, como recomendación, agrega un campo description a la sección de parámetros y al cuerpo de la solicitud.

Tu documento de OpenAPI contiene información como la siguiente:

{
 "swagger": "2.0",
 "info": {
  "version": "1.0.0",
  "title": "example-project-12345.appspot.com"
 },
 "host": "example-project-12345.appspot.com",

Los valores de estos campos se muestran en el portal de la siguiente forma:

• title: el valor del título se muestra en la página principal de tu portal en la sección que enumera las API del proyecto, en la página principal de la API (con la palabra documentación adjunta) y en la barra de título de la API.

• host: el valor para el host (que también es el nombre del servicio de Endpoints) se muestra en la página principal del portal en la sección que enumera las API del proyecto y en la página Configuración, en la lista desplegable que se muestra en la pestaña API.

• version: el número de versión principal se usa en la URL del portal de la API.

Es posible que desees cambiar el valor en el campo title y agregar un campo description para la API. Por ejemplo:

{
 "swagger": "2.0",
 "info": {
  "version": "1.0.0",
  "title": "Endpoints Frameworks Example",
  "description": "A simple Cloud Endpoints Frameworks API example."
 },
 "host": "example-project-12345.appspot.com",

Volver a generar SmartDocs

Permisos requeridos para esta tarea

Para volver a generar SmartDocs, debes implementar tu configuración actualizada de Endpoints. La función de Editor de la configuración del servicio que se otorga en el servicio tiene el mínimo de permisos requeridos para volver a implementar la configuración de Endpoints. Consulta Otorga y revoca el acceso a la API para obtener más información sobre cómo asignar esta función.

Para volver a generar la documentación de referencia:

1. Haz los cambios en el archivo openapi.json que Endpoints Frameworks generó.

2. Vuelve a implementar openapi.json:

   gcloud endpoints services deploy openapi.json
   

3. Actualiza la página del portal.

4. Guarda el archivo openapi.json modificado en una ubicación en la que no se lo pueda reemplazar si luego necesitas volver a generar el archivo openapi.json. Si haces modificaciones a la API y vuelves a generar el archivo openapi.json, necesitas combinar los cambios en el openapi.json recién generado con los cambios que realizaste antes.

Consulta gcloud endpoints services deploy para obtener más información sobre el comando.