Descripción general de OpenAPI

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

Puedes implementar tu API con cualquier marco de trabajo REST disponible públicamente, como Django o Jersey.

Describes tu API en un archivo YAML o al que se hace referencia como un documento de OpenAPI. En esta página, se describen algunos de los beneficios del uso de OpenAPI, se muestra un documento básico de OpenAPI y se proporciona información adicional para ayudarte a comenzar con OpenAPI.

Versiones de OpenAPI compatibles

API Gateway admite las siguientes versiones de OpenAPI:

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

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

Compatibilidad con versiones de parche

La especificación de OpenAPI indica que las versiones de parche (p.ej., 3.0.1 y 3.0.2) solo introducen correcciones o aclaraciones, y no agregan funciones nuevas. Como resultado, API Gateway admite todas las versiones de parche de la versión 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, como se describe en Versiones compatibles de OpenAPI.

Beneficios

Uno de los beneficios principales del uso de OpenAPI es para la documentación; una vez que tienes un documento de OpenAPI que describe tu API, puedes generar la documentación de referencia para tu API.

El uso de OpenAPI tiene otros beneficios. Por ejemplo, puedes hacer lo siguiente:

  • Generar bibliotecas cliente en decenas de lenguajes
  • Generar stubs de servidores
  • Usar 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 de REST y define información como la siguiente:

  • El nombre y la descripción de la API
  • Los extremos (rutas) individuales en la API
  • Cómo se autentican los emisores

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 aún no te familiarizaste con OpenAPI, consulta la estructura básica de Swagger, que proporciona un documento de OpenAPI de muestra y explica brevemente cada sección del archivo. En el siguiente ejemplo, se ilustra 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 aún no te familiarizaste con OpenAPI, consulta la estructura básica de Swagger, que proporciona un documento de OpenAPI de muestra y explica cada sección del archivo. En el siguiente ejemplo, se ilustra 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:

Genera un documento de OpenAPI

Según el lenguaje que utilizas, es posible que puedas generar un documento de OpenAPI. En Java, existen proyectos de código abierto para Jersey y Spring que pueden generar un documento de OpenAPI desde anotaciones. También existe un complemento de Maven. Para los desarrolladores de Python y Node, OpenAPI.Tools puede ser un proyecto interesante.

La comunidad de OpenAPI está desarrollando continuamente herramientas de ayuda para la composición (y, en el caso de algunos lenguajes, la generación automática) de documentos de OpenAPI. Consulta La especificación de OpenAPI para obtener más información.

¿Qué sigue?