Información general sobre OpenAPI

API Gateway admite APIs que se describen mediante versiones compatibles de la especificación de OpenAPI.

Tu API se puede implementar con cualquier framework REST disponible públicamente, como Django o Jersey.

Describe tu API en un archivo YAML denominado documento de OpenAPI. En esta página se describen algunas de las ventajas de usar OpenAPI, se muestra un documento de OpenAPI básico y se proporciona información adicional para ayudarte a empezar a usar OpenAPI.

Versiones compatibles de OpenAPI

API Gateway admite las siguientes versiones de OpenAPI:

  1. OpenAPI 2.0 (antes Swagger)
  2. OpenAPI 3.0.x

Las especificaciones oficiales de cada versión están disponibles en la iniciativa OpenAPI.

Compatibilidad con versiones de parche

La especificación de OpenAPI indica que las versiones de parche (por ejemplo, 3.0.1 y 3.0.2) solo incluyen correcciones o aclaraciones y no añaden funciones nuevas. Por lo tanto, API Gateway admite todas las versiones de parche de 3.0.

Terminología

En toda la documentación de API Gateway, OpenAPI 3.x hace referencia a todas las versiones compatibles de OpenAPI 3, tal como se describe en Versiones compatibles de OpenAPI.

Ventajas

Una de las principales ventajas de usar OpenAPI es la documentación. Una vez que tengas un documento de OpenAPI que describa tu API, podrás generar documentación de referencia para ella.

Usar OpenAPI tiene otras ventajas. Por ejemplo, puedes:

  • Generar bibliotecas de cliente en decenas de idiomas
  • Generar stubs de servidor
  • Usa proyectos para verificar tu conformidad y generar muestras

Estructura básica de un documento de OpenAPI

Un documento de OpenAPI describe la superficie de tu API REST y define información como la siguiente:

  • El nombre y la descripción de la API
  • Los endpoints (rutas) individuales de la API
  • Cómo se autentican las personas que llaman

La estructura de tu documento de OpenAPI depende de la versión de OpenAPI que utilices. En los siguientes ejemplos se describe la estructura de OpenAPI 2.0 y OpenAPI 3.x.

OpenAPI 2.0

Si no has usado nunca OpenAPI, consulta la estructura básica de Swagger, que proporciona un documento de ejemplo de OpenAPI (también denominado especificación de Swagger) y explica brevemente cada sección del archivo. En el siguiente ejemplo se muestra esta estructura básica:

swagger: "2.0"
info:
  title: API_ID optional-string
  description: "Get the name of an airport from its three-letter IATA code."
  version: "1.0.0"
host: DNS_NAME_OF_DEPLOYED_API
schemes:
  - "https"
paths:
  "/airportName":
    get:
      description: "Get the airport name for a given IATA code."
      operationId: "airportName"
      parameters:
        -
          name: iataCode
          in: query
          required: true
          type: string
      responses:
        200:
          description: "Success."
          schema:
            type: string
        400:
          description: "The IATA code is invalid or missing."

OpenAPI 3.x

Si no has usado nunca OpenAPI, consulta la estructura básica de Swagger, que proporciona un documento de ejemplo de OpenAPI y explica cada sección del archivo. En el siguiente ejemplo se muestra esta estructura básica:

openapi: 3.0.4
info:
  title: API_ID optional-string
  description: Get the name of an airport from its three-letter IATA code
  version: 1.0.0
x-google-api-management:
  backend:
    BACKEND_NAME
      address: https://BACKEND_URL/airportNameGET
      pathTranslation: APPEND_PATH_TO_ADDRESS
      protocol: "http/1.1"
x-google-backend: BACKEND_NAME
paths:
  /airportName:
    get:
      summary: Get the airport name for a given IATA code
      operationId: airportName
      responses:
        '200':
          description: A successful response
          content:
            application/json:
              schema:
                type: string
      parameters:
        - name: iataCode
          in: query
          required: true
          schema:
            type: string

Además de la estructura básica, usa el archivo openapi.yaml para configurar lo siguiente:

Generar un documento de OpenAPI

En función del idioma que uses, es posible que puedas generar un documento de OpenAPI. En Java, hay proyectos de código abierto para Jersey y Spring que pueden generar un documento de OpenAPI a partir de anotaciones. También hay un plugin de Maven. Para los desarrolladores de Python y Node, OpenAPI.Tools puede ser un proyecto interesante.

La comunidad de OpenAPI desarrolla continuamente herramientas para ayudar en la composición (y, en algunos idiomas, en la generación automática) de documentos de OpenAPI. Consulta la sección Especificación de OpenAPI para obtener más información.

Siguientes pasos