Administra especificaciones de API

Esta página se aplica a Apigee y Apigee Hybrid.

En este documento, se describe cómo administrar las especificaciones de API en el concentrador de APIs. Consulta también Introducción a las especificaciones de API.

Agrega una especificación de la API a una versión

Puedes agregar una o más especificaciones a una versión de API. Puedes elegir estas opciones:

Agrega una especificación cuando crees una versión
Agrega una especificación a una versión existente

Agrega una especificación cuando crees una versión

Con la IU solo, puedes agregar una especificación de la API al mismo tiempo que creas una versión. Puedes proporcionar la URL a una especificación a la que puedas acceder o subir un archivo de especificación directamente desde tu sistema.

Console

Para agregar una especificación a una versión nueva, haz lo siguiente:

Sigue los pasos que se indican en Crea una versión de API para comenzar. Cuando llegues a la página Agregar una versión nueva, puedes agregar un archivo de especificación a la versión de forma opcional:
1. Ingresa un nombre visible para el archivo de especificación. Puedes usar cualquier nombre que desees.
2. Selecciona el tipo de archivo de especificación. El tipo de especificación es un atributo del sistema configurable. Consulta también Atributos del sistema.
3. Proporciona un URI que apunte a un archivo de especificación de API válido al que tengas acceso o navega a un archivo de especificación de API en tu sistema.
4. Opcional: Si deseas aplicar una validación estricta a la especificación subida, selecciona la casilla de verificación Restringir la carga de los archivos de especificación que contengan errores. Si se selecciona esta opción, no se subirán las especificaciones que contengan errores de validación. De forma predeterminada, las especificaciones que contienen errores se suben.
Completa la página Agregar una versión nueva y haz clic en Crear cuando termines.

Agrega una especificación a una versión existente

Puedes usar la IU o la API de REST para agregar una especificación de API a una versión existente.

Console

Para agregar una especificación directamente a una versión, haz lo siguiente:

En la consola de Google Cloud, dirígete a la página del concentrador de APIs.
Ir al concentrador de APIs
Haz clic en APIs.
Ubica la API con la versión que deseas modificar. Usa el Filtro para especificar palabras clave a fin de filtrar la lista de APIs. Si es necesario, usa Buscar para ubicar una API.
Selecciona una API
Haz clic en Agregar archivo de especificación.
Ingresa un nombre visible para el archivo de especificación. Puedes usar cualquier nombre que desees.
Selecciona el tipo de archivo de especificación. El tipo de especificación es un atributo del sistema configurable. Consulta también Atributos del sistema.
Proporciona un URI que apunte a un archivo de especificación de API válido al que tengas acceso o navega a un archivo de especificación de API en tu sistema.
Opcional: Si deseas aplicar una validación estricta a la especificación subida, selecciona la casilla de verificación Restringir la carga de los archivos de especificación que contengan errores. Si se selecciona esta opción, no se subirán las especificaciones que contengan errores de validación. De forma predeterminada, las especificaciones que contienen errores se suben.
Selecciona la versión a la que se agregará el archivo de especificación.
Haz clic en Crear.
Nota: El análisis de especificaciones de la API solo es compatible con especificaciones de OpenAPI (v.2.0, v3.0 y v3.1) en formatos JSON y YAML.

REST

Para agregar una especificación de la API a una versión, usa la API Agregar especificaciones de la API:

curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  'https://apihub.googleapis.com/v1/projects/API_PROJECT/locations/API_LOCATION/apis/API_ID/versions/VERSION_ID/specs?spec_id=SPEC_ID' \
  -d "DATA_FILE or URI"

Reemplaza lo siguiente:

API_PROJECT: el nombre de tu proyecto host del concentrador de APIs. El proyecto host se seleccionó cuando se aprovisionó el concentrador de APIs.
API_LOCATION: La ubicación del proyecto host. La ubicación se eligió cuando se aprovisionó el concentrador de APIs.
API_ID: el ID único de un recurso de API.
VERSION_ID: El ID de una versión adjunta al recurso de la API.
SPEC_ID: (Opcional) El identificador de la especificación. Si no se proporciona, se usará un ID generado por el sistema. El nombre debe ser una string de 4 a 63 caracteres, en la que los caracteres válidos son /[a-z][0-9]-/.
DATA_FILE or URI: un archivo codificado en Base64 que contiene una especificación de API válida o un vínculo a una especificación. Consulta el ejemplo de REST.

Ejemplo de REST

En este ejemplo, se crea una especificación nueva en el concentrador de API con una especificación de OpenAPI codificada en Base64. Después de la carga, el concentrador de API analiza la especificación y crea una entidad de especificación nueva que incluye metadatos descriptivos más conjuntos de entidades de operación y definición.

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d "@data.json" \
  https://apihub.googleapis.com/v1/projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/specs?spec_id=dstreetcarts-spec

Resultado de muestra:

{
    "name": "projects/common-dev-1/locations/us-central1/apis/streetcarts/versions/streetcartsv1/specs/dstreetcarts-spec",
    "displayName": "Test Spec 1",
    "specType": {},
    "contents": {
      "contents": [Base64-encoded contents of an OpenAPI 3.0.2 file] },
    "details": {
      "description": "This is a sample Pet Store Server based on the OpenAPI 3.0 specification.\nYou can find out more about Swagger at [https://swagger.io](https://swagger.io).",
      "openApiSpecDetails": {
        "format": "OPEN_API_SPEC_3_0",
        "version": "1.0.11"
      }
    },
    "createTime": "2024-04-04T22:39:05.674986Z",
    "updateTime": "2024-04-04T22:39:05.674986Z"
  }

Para mostrar los detalles de la especificación, sigue estos pasos:

curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" \
  https://apihub.googleapis.com/v1/projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1

Resultado:

{
  "name": "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1",
  "displayName": "Test Version 3",
  "documentation": {},
  "specs": [
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/specs/dstreetcarts-spec"
  ],
  "apiOperations": [
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/operations/listpets",
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/operations/createpets",
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/operations/deletepet",
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/operations/getpetbyid",
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/operations/updatepet"
  ],
  "definitions": [
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/definitions/pet"
  ],
  "createTime": "2024-04-04T14:53:57.299213423Z",
  "updateTime": "2024-04-04T14:53:58.027321138Z"
}

Enumerar especificaciones

En esta sección, se explica cómo enumerar las especificaciones asociadas con una versión de API.

Console

Para enumerar las especificaciones con la IU, haz lo siguiente:

En la consola de Google Cloud, dirígete a la página del concentrador de APIs.
Ir al centro de APIs
Haz clic en APIs.
Usa el Filtro para especificar palabras clave a fin de filtrar la lista de APIs. Si es necesario, usa Buscar para ubicar una API.
Haz clic en una API para ver sus detalles.
En la pestaña Versiones, busca la versión que deseas inspeccionar.
Selecciona una versión.
Todas las especificaciones vinculadas a la versión se enumeran en la sección Archivo de especificaciones.

REST

Para enumerar las especificaciones asociadas con una versión de API, usa la API de enumerar especificaciones:

curl "https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/apis/API_ID/versions/VERSION_ID/specs"
      -H "Authorization: Bearer: $(gcloud auth print-access-token)" -X GET -H "Content-Type: application/json"

Reemplaza lo siguiente:

HUB_PROJECT: el nombre de tu proyecto host del concentrador de APIs. El proyecto host se seleccionó cuando se aprovisionó el concentrador de APIs.
HUB_LOCATION: La ubicación del proyecto host. La ubicación se eligió cuando se aprovisionó el concentrador de APIs.
API_ID: el ID único del recurso de la API.
VERSION_ID: el ID único de la versión.

Obtén detalles de las especificaciones

En esta sección, se explica cómo obtener los detalles sobre una especificación de API asociada a una versión.

Console

Para ver los detalles de una especificación a través de la IU, haz lo siguiente:

En la consola de Google Cloud, dirígete a la página del concentrador de APIs.
Ir al concentrador de APIs
Haz clic en APIs.
Ubica la API con la versión que contiene la especificación que deseas inspeccionar. Usa el Filtro para especificar palabras clave a fin de filtrar la lista de APIs. Si es necesario, usa Buscar para ubicar una API.
Haz clic en una API para ver sus detalles.
En la pestaña Versiones, busca la versión que deseas inspeccionar.
Selecciona una versión.
En la sección Archivo de especificación, selecciona una especificación para ver sus detalles.

REST

Para ver los detalles de una especificación, usa la API Obtener detalles de las especificaciones:

curl "https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/apis/API_ID/versions/VERSION_ID/specs/SPEC_ID"
  -H "Authorization: Bearer: $(gcloud auth print-access-token)" -X GET -H "Content-Type: application/json"

Reemplaza lo siguiente:

HUB_PROJECT: el nombre de tu proyecto host del concentrador de APIs. El proyecto host se seleccionó cuando se aprovisionó el concentrador de APIs.
HUB_LOCATION: La ubicación del proyecto host. La ubicación se eligió cuando se aprovisionó el concentrador de APIs.
API_ID: el ID único del recurso de la API.
VERSION_ID: el ID único de la versión.
SPEC_ID: el ID único de la especificación.

Resultado de muestra:

{
  "name": "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/specs/dstreetcarts-spec",
  "displayName": "Test Spec 1",
  "details": {
    "description": "This is a sample Pet Store Server based on the OpenAPI 3.0 specification.\nYou can find out more about Swagger at [https://swagger.io](https://swagger.io).",
    "openApiSpecDetails": {
      "format": "OPEN_API_SPEC_3_0",
      "version": "1.0.11"
    }
  },
  "createTime": "2024-04-04T22:39:05.098508600Z",
  "updateTime": "2024-04-04T22:39:06.661264958Z"
}

Borra una especificación de API

En esta sección, se explica cómo borrar una especificación de API de una versión. Si borras una especificación, también se borrarán las operaciones asociadas de la versión.

Console

Para borrar los recursos de API con la IU, haz lo siguiente:

En la consola de Google Cloud, dirígete a la página del concentrador de APIs.
Ir al concentrador de APIs
Haz clic en APIs.
Ubica la API con la versión que contiene la especificación que deseas borrar. Usa el Filtro para especificar palabras clave a fin de filtrar la lista de APIs. Si es necesario, usa Buscar para ubicar una API.
Haz clic en una API para ver sus detalles.
En la pestaña Versiones, busca la versión que contiene la especificación que deseas borrar.
Selecciona la versión.
En la sección Archivo de especificaciones, selecciona Borrar en el menú Acciones en la fila de la especificación que deseas borrar.
Haz clic en Borrar.

REST

Para borrar un recurso de API del concentrador de APIs, usa la API Borrar recurso de API:

curl "https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/apis/API_ID/versions/VERSION_ID/specs/SPEC_ID"
  -H "Authorization: Bearer: $(gcloud auth print-access-token)" -X DELETE -H "Content-Type: application/json"

Reemplaza lo siguiente:

HUB_PROJECT: el nombre de tu proyecto host del concentrador de APIs. El proyecto host se seleccionó cuando se aprovisionó el concentrador de APIs.
HUB_LOCATION: La ubicación del proyecto host. La ubicación se eligió cuando se aprovisionó el concentrador de APIs.
API_ID: el ID único del recurso de la API.
VERSION_ID: el ID único de la versión.
SPEC_ID: el ID de único de la especificación que se borrará.

Edita los metadatos de especificación

Puedes editar algunos de los metadatos asociados con una especificación almacenada en el concentrador de APIs. Para obtener una lista de metadatos que puedes editar, consulta Parche de especificaciones de API.

Console

Puedes realizar cambios en una especificación existente a través de la consola de Google Cloud. Por ejemplo, puedes cambiar el nombre visible, subir un nuevo archivo de especificación, cambiar el tipo de archivo y editar atributos:

En la consola de Google Cloud, dirígete a la página del concentrador de APIs.
Ir al concentrador de APIs
Haz clic en APIs.
Ubica la API con la versión que contiene la especificación que deseas editar. Usa el Filtro para especificar palabras clave a fin de filtrar la lista de APIs. Si es necesario, usa Buscar para ubicar una API.
Haz clic en una API para ver sus detalles.
En la pestaña Versiones, busca la versión que contiene la especificación que deseas editar.
Selecciona la versión.
En la página Versiones, busca la especificación que deseas editar.
Selecciona Editar en el menú Acciones de la fila de la especificación que deseas editar.
En el panel de edición de la especificación, puedes cambiar cualquiera de los siguientes metadatos de especificación:
- Nombre visible
- Tipo del archivo de especificación
- Documento de especificación: Explora un archivo de especificación nuevo para subirlo.
- Opcional: Si deseas aplicar una validación estricta a la especificación subida, selecciona la casilla de verificación Restringir la carga de los archivos de especificación que contengan errores. Si se selecciona esta opción, no se subirán las especificaciones que contengan errores de validación. De forma predeterminada, las especificaciones que contienen errores se suben.
- Atributos definidos por el usuario (si existen)
Haz clic en Guardar.

REST

Para editar una especificación con la API de REST, haz lo siguiente:

curl "https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/apis/API_ID/versions/VERSION_ID/specs/SPEC_ID"
    -H "Authorization: Bearer: $(gcloud auth print-access-token)" -X PATCH -H "Content-Type: application/json"
    '{
      "display-name": DISPLAY_NAME.  # Use the request body to specify attribute changes
      "contents": {
         "contents": Base64-encoded string
         "mimeType": MIME_TYPE
      }
    }'

Reemplaza lo siguiente:

HUB_PROJECT: el nombre de tu proyecto host del concentrador de APIs. El proyecto host se seleccionó cuando se aprovisionó el concentrador de APIs.
HUB_LOCATION: La ubicación del proyecto host. La ubicación se eligió cuando se aprovisionó el concentrador de APIs.
API_ID: el ID único del recurso de la API.
VERSION_ID: el ID único de la versión.
SPEC_ID: el ID único de la especificación.
Cuerpo de la solicitud: usa el cuerpo de la solicitud para especificar los atributos que deseas cambiar. Consulta Definición de recursos de especificación.

Observa los resultados de lint de la especificación

El centro de la API proporciona un linter (validador) integrado (Spectral) que valida la especificación de Open API de la API. Consulta Valida las especificaciones de la API.

En la consola de Google Cloud, dirígete a la página del concentrador de APIs.
Ir al centro de APIs
Haz clic en APIs.
Ubica la API con la versión que contiene la especificación que deseas inspeccionar. Usa el Filtro para especificar palabras clave a fin de filtrar la lista de APIs. Si es necesario, usa Buscar para ubicar una API.
Haz clic en una API para ver sus detalles.
En la pestaña Versiones, busca la versión que contiene la especificación que deseas inspeccionar.
Haz clic en Ver resultados en la columna de resultados de lint para verlos.

Obtén el contenido de la especificación

Esta función te permite revisar el contenido de una especificación que se subió al centro de APIs.

Console

Para ver los detalles de una especificación a través de la IU, haz lo siguiente:

En la consola de Google Cloud, dirígete a la página del concentrador de APIs.
Ir al concentrador de APIs
Haz clic en APIs.
Ubica la API con la versión que contiene la especificación que deseas borrar. Usa el Filtro para especificar palabras clave a fin de filtrar la lista de APIs. Si es necesario, usa Buscar para ubicar una API.
Haz clic en una API para ver sus detalles.
En la pestaña Versiones, busca la versión que contiene la especificación que deseas inspeccionar.
Haz clic en el nombre de la especificación para ver su contenido.

REST

La API recupera el contenido sin procesar codificado en Base64 de una especificación de API que se subió al centro de APIs. Usa la API Obtener contenido de la especificación:

curl "https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/apis/API_ID/versions/VERSION_ID/specs/SPEC_ID:contents"
  -H "Authorization: Bearer: $(gcloud auth print-access-token)" -X GET -H "Content-Type: application/json"

Reemplaza lo siguiente:

HUB_PROJECT: el nombre de tu proyecto host del concentrador de APIs. El proyecto host se seleccionó cuando se aprovisionó el concentrador de APIs.
HUB_LOCATION: La ubicación del proyecto host. La ubicación se eligió cuando se aprovisionó el concentrador de APIs.
API_ID: el ID único del recurso de la API.
VERSION_ID: el ID único de la versión.
SPEC_ID: el ID único de la especificación.

Resultado de muestra:

{
  "contents": "Base64-encoded file contents"
}