Descripción general de OpenAPI

API Gateway admite las API que se describen con la especificación de OpenAPI, versión 2.0. 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.

Ventajas

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, es fácil 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

Si aún no te familiarizaste con OpenAPI, consulta el sitio web 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."

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

Cómo generar 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 puede generar un documento de OpenAPI a partir de 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 OpenAPI Specification para obtener más información.

¿Qué sigue?