Modificar Cloud Endpoints para usar OpenAPI 3.x

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

Antes de empezar

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

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

Sigue estos pasos para modificar una configuración de endpoints de OpenAPI 2.0 y usar OpenAPI 3.x.

Ver el historial de implementaciones

Para ver el historial de despliegues, sigue estos pasos:

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

    Ir a la página Servicios de Endpoints

  2. En la lista de proyectos, selecciona el tuyo.

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

  4. Para ver una lista de las implementaciones de configuración de servicios, haz clic en la pestaña Historial de implementaciones. En la lista se muestra lo siguiente:

    • El ID de configuración.
    • Fecha en la que se implementó la configuración del servicio.
    • Quién desplegó la configuración del servicio.

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.

Convertir el documento OpenAPI a OpenAPI 3.x

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

Después de la conversión inicial a OpenAPI 3.x, aplica manualmente los cambios adicionales al documento para que se ajuste a OpenAPI 3.x y asegúrate de que sea compatible con las extensiones y las 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 con claves de API de OpenAPI lista para usar. Las herramientas de conversión suelen encargarse de esto automáticamente. No es necesario hacer ningún cambio manualmente.
Autenticación JWT x-google-audiences, etc. x-google-auth En las extensiones de OpenAPI 2.0, la configuración de OAuth se define 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 no cambian.
Cuota x-google-management, x-google-quota x-google-api-management, x-google-quota En las extensiones de OpenAPI 2.0, se definen las métricas y las cuotas en x-google-management y se adjuntan con x-google-quota. Las herramientas de conversión dejan estas extensiones en su sitio. Mueve manualmente las métricas y la configuración de cuota de x-google-management a x-google-api-management. Cambia la configuración para usar claves YAML y elimina 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, los backends se definen en x-google-backend y la configuración se aplica donde se define. En las extensiones de OpenAPI 3.x, se define el backend en x-google-api-management y, a continuación, se aplica con x-google-backend. Las herramientas de conversión dejan esta extensión en su sitio. 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.
Endpoints x-google-endpoints x-google-endpoint, servers En las extensiones de OpenAPI 2.0, se define la configuración de los endpoints en x-google-endpoints. En las extensiones de OpenAPI 3.x, se usa x-google-endpoint, pero es una extensión de servers en lugar de la raíz. Las herramientas de conversión dejan esta extensión en su sitio. Mueve manualmente este elemento a servers y elimina 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 las APIs x-google-api-name x-google-api-management En las extensiones de OpenAPI 2.0, los nombres de las APIs se definen 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 NO COMPATIBLE Elimina esto del documento de OpenAPI. Endpoints no admite esta opción en OpenAPI 3.x.

Volver a desplegar la configuración del servicio

Cada vez que cambies 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 tu API. No es necesario que vuelvas a implementar ni reiniciar ESP si ya lo has hecho con la opción rollout definida como managed. Esta opción configura ESP para que use la última configuración de servicio implementada. Si especifica esta opción, hasta 5 minutos después de desplegar una nueva configuración de servicio, ESP detectará el cambio y empezará a usarlo automáticamente. Te recomendamos que especifiques esta opción en lugar de un ID de configuración específico para que la use el ESP.

Para implementar tu documento de OpenAPI, sigue estos pasos:

  1. Cambia al directorio que contiene tu documento de OpenAPI.

  2. Valida el ID del proyecto devuelto por el siguiente comando para asegurarte de que el servicio no se ha creado en el proyecto incorrecto.

    gcloud config list project

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

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

  3. Ejecuta el siguiente comando y sustituye 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 ejecutes el comando anterior, Service Management creará un servicio de Endpoints en el proyecto predeterminado con un nombre que coincida con el texto que hayas especificado en el campo host de tu documento OpenAPI y subirá la configuración del servicio.

Mientras crea y configura el servicio, Gestión de servicios muestra información en la terminal. Si se completa correctamente, verás una línea como la siguiente que muestra el ID de configuración del servicio 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.

Una vez que se haya completado la implementación, puedes ver la API en la página Endpoints > Services de la consola de Google Cloud .

Si aparece un mensaje de error, consulta Solucionar problemas de configuración e implementación de endpoints.

Siguientes pasos