Administra especificaciones de API

Console

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

1. 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.
2. Completa la página Agregar una versión nueva y haz clic en Crear cuando termines.

Console

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

1. En la consola de Google Cloud, dirígete a la página del concentrador de APIs.

   Ir al concentrador de APIs
2. Haz clic en APIs.
3. 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.
4. Selecciona una API
5. Haz clic en Agregar archivo de especificación.
6. Ingresa un nombre visible para el archivo de especificación. Puedes usar cualquier nombre que desees.
7. 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.
8. 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.
9. 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.
10. Selecciona la versión a la que se agregará el archivo de especificación.
11. Haz clic en Crear.

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"
}

Console

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

1. En la consola de Google Cloud, dirígete a la página del concentrador de APIs.

   Ir al centro de APIs
2. Haz clic en APIs.
3. Usa el Filtro para especificar palabras clave a fin de filtrar la lista de APIs. Si es necesario, usa Buscar para ubicar una API.
4. Haz clic en una API para ver sus detalles.
5. En la pestaña Versiones, busca la versión que deseas inspeccionar.
6. Selecciona una versión.
7. 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.

Console

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

1. En la consola de Google Cloud, dirígete a la página del concentrador de APIs.

   Ir al concentrador de APIs
2. Haz clic en APIs.
3. 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.
4. Haz clic en una API para ver sus detalles.
5. En la pestaña Versiones, busca la versión que deseas inspeccionar.
6. Selecciona una versión.
7. 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"
}

Console

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

1. En la consola de Google Cloud, dirígete a la página del concentrador de APIs.

   Ir al concentrador de APIs
2. Haz clic en APIs.
3. 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.
4. Haz clic en una API para ver sus detalles.
5. En la pestaña Versiones, busca la versión que contiene la especificación que deseas borrar.
6. Selecciona la versión.
7. En la sección Archivo de especificaciones, selecciona Borrar en el menú Acciones en la fila de la especificación que deseas borrar.
8. 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á.

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:

1. En la consola de Google Cloud, dirígete a la página del concentrador de APIs.

   Ir al concentrador de APIs
2. Haz clic en APIs.
3. 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.
4. Haz clic en una API para ver sus detalles.
5. En la pestaña Versiones, busca la versión que contiene la especificación que deseas editar.
6. Selecciona la versión.
7. En la página Versiones, busca la especificación que deseas editar.
8. Selecciona Editar en el menú Acciones de la fila de la especificación que deseas editar.
9. 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)
10. 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.

Console

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

1. En la consola de Google Cloud, dirígete a la página del concentrador de APIs.

   Ir al concentrador de APIs
2. Haz clic en APIs.
3. 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.
4. Haz clic en una API para ver sus detalles.
5. En la pestaña Versiones, busca la versión que contiene la especificación que deseas inspeccionar.
6. 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"
}