Modifica Cloud Endpoints para usar OpenAPI 3.x

En esta página, se describe cómo usar una especificación de OpenAPI 3.x cuando configuras Endpoints.

Antes de comenzar

  • Confirma que tienes una instancia de Endpoints existente configurada con una especificación de OpenAPI 2.0.
  • Instala la CLI de gcloud. Para obtener más información, consulta Instala Google Cloud CLI.

Modifica la configuración de Endpoints para usar OpenAPI 3.x

Completa los siguientes pasos para modificar una configuración existente de Endpoints con OpenAPI 2.0 para usar OpenAPI 3.x.

Cómo ver el historial de implementaciones

Para ver el historial de implementaciones, sigue estos pasos:

  1. En la consola de Google Cloud , ve a la página Endpoints > Servicios.

    Ir a la página Servicios de Endpoints

  2. Selecciona el proyecto desde la lista de proyectos.

  3. Si tienes más de una API, selecciona una de la lista.

  4. Haz clic en la pestaña Historial de implementaciones para ver la lista de implementaciones de configuración del servicio. La lista muestra:

    • El ID de configuración
    • La fecha en que se implementó la configuración del servicio
    • Quién implementó la configuración del servicio

Cómo ver la configuración del servicio

En la pestaña Historial de implementaciones, selecciona la implementación más reciente de la lista. Se muestra el contenido del archivo de configuración del servicio implementado.

Convierte el documento de OpenAPI a OpenAPI 3.x

Convierte tu documento de OpenAPI 2.0 a OpenAPI 3.x. Puedes usar una herramienta que admita esta conversión a OpenAPI 3.x. Por ejemplo, Swagger Editor proporciona una utilidad de conversión.

Después de la conversión inicial a OpenAPI 3.x, aplica manualmente los cambios adicionales al documento para alinearlo con OpenAPI 3.x y garantizar la compatibilidad con las extensiones y funciones de Endpoints.

En la siguiente tabla, se describen los cambios necesarios:

Función OpenAPI 2.0 OpenAPI 3.x Descripción del cambio
Clave de API securityDefinitions securitySchemes Las claves de API usan la compatibilidad lista para usar con claves de API de OpenAPI. Por lo general, las herramientas de conversión se encargan de esto automáticamente. No se requieren cambios manuales.
Autenticación de JWT x-google-audiences, etcétera x-google-auth En las extensiones de OpenAPI 2.0, defines la configuración de OAuth con extensiones individuales en una instancia de securityDefinition. Las herramientas de conversión convierten la instancia del esquema de seguridad en #/components/securitySchemes y dejan las extensiones. Modifica manualmente estas extensiones para que sean elementos secundarios de x-google-auth y quita el prefijo x-google-. Los valores permanecen sin cambios.
Cuota x-google-management, x-google-quota x-google-api-management, x-google-quota En las extensiones de OpenAPI 2.0, defines las métricas y la cuota en x-google-management y las adjuntas con x-google-quota. Las herramientas de conversión dejan estas extensiones en su lugar. Mueve manualmente la configuración de las métricas y las cuotas de x-google-management a x-google-api-management. Cambia la configuración para usar claves YAML y quita valueType, metricKind y unit. Quita metricCosts de las instancias de x-google-quota.
Backends x-google-backend x-google-api-management, x-google-backend En las extensiones de OpenAPI 2.0, defines los backends en x-google-backend, y la configuración se aplica donde se define. En las extensiones de OpenAPI 3.x, defines el backend en x-google-api-management y, luego, lo aplicas con x-google-backend. Las herramientas de conversión dejan esta extensión en su lugar. Mueve manualmente la configuración a x-google-api-management. Modifica las instancias de x-google-backend para que hagan referencia a esa configuración.
Extremos x-google-endpoints x-google-endpoint, servers En las extensiones de OpenAPI 2.0, defines la configuración de los extremos en x-google-endpoints. En las extensiones de OpenAPI 3.x, se usa x-google-endpoint, pero es una extensión en servers en lugar de en la raíz. Las herramientas de conversión dejan esta extensión en su lugar. Mueve esto de forma manual a servers y quita el campo name. Por ejemplo: 
# OpenAPI 2.0
x-google-endpoints:
- name: "my-api.apigateway.my-project.cloud.goog"
  allowCors: True
# OpenAPI 3.x
servers:
- url: https://my-api.apigateway.my-project.cloud.goog/
  x-google-endpoint:
    allowCors: True
Nombres de la API x-google-api-name x-google-api-management En las extensiones de OpenAPI 2.0, defines los nombres de la API en x-google-api-name. En las extensiones de OpenAPI 3.x, se usa un campo apiName en x-google-api-management. Mueve manualmente esta configuración a x-google-api-management.
Permitir todo el tráfico x-google-allow INCOMPATIBLE Quita esto del documento de OpenAPI. Endpoints no admite esta función en OpenAPI 3.x.

Vuelve a implementar la configuración del servicio

Cuando quieras cambiar algo en tu documento de OpenAPI, asegúrate de volver a implementarlo para que Endpoints tenga la versión más reciente de la configuración de servicio de la API. No es necesario volver a implementar o reiniciar el ESP si ya implementaste el ESP con la opción rollout configurada como managed. Esta opción configura el ESP para que use la configuración del servicio implementado más reciente. Cuando especificas esta opción, el ESP detecta el cambio y comienza a usarlo automáticamente hasta 5 minutos después de implementar una nueva configuración de servicio. Recomendamos que especifiques esta opción en lugar de un ID de configuración específico para que use el ESP.

Para implementar tu documento de OpenAPI, sigue estos pasos:

  1. Cambia el directorio a la ubicación que contiene el documento de OpenAPI.

  2. Valida el ID del proyecto que muestra el siguiente comando para asegurarte de que el servicio no se cree en el proyecto equivocado.

    gcloud config list project

    Si necesitas cambiar el proyecto predeterminado, ejecuta el siguiente comando y reemplaza YOUR_PROJECT_ID por el Google Cloud ID del proyecto en el que quieres crear el servicio:

    gcloud config set project <var>YOUR_PROJECT_ID</var>

  3. Ejecuta el siguiente comando y reemplaza YOUR_OPENAPI_DOCUMENT por el nombre del documento de OpenAPI que describe tu API:

    gcloud endpoints services deploy <var>YOUR_OPENAPI_DOCUMENT</var>

La primera vez que ejecutas el comando anterior, Service Management crea un nuevo servicio de Endpoints en el proyecto predeterminado con un nombre que coincide con el texto que especificaste en el campo host en tu documento de OpenAPI y, además, sube la configuración del servicio.

Mientras se crea y configura el servicio, Administración de servicio exporta la información a la terminal. Cuando el proceso finalice con éxito, verás una línea como la siguiente, que indica el ID de configuración y el nombre del servicio:

Service Configuration [2017-02-13r0] uploaded for service [echo-api.endpoints.example-project-12345.cloud.goog]

En el ejemplo anterior, 2017-02-13r0 es el ID de configuración del servicio y echo-api.endpoints.example-project-12345.cloud.goog es el nombre del servicio.

Después de una implementación exitosa, puedes ver la API en la página Endpoints > Servicios de la consola de Google Cloud .

Si recibes un mensaje de error, consulta Solucionar problemas en la implementación de la configuración de Endpoints.

¿Qué sigue?