Información general sobre OpenAPI

API Gateway admite APIs descritas mediante la especificación de OpenAPI, versión 2.0. 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.

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

Si no conoces OpenAPI, consulta el sitio web 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."

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. Si eres desarrollador 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