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:
- El campo
title
con el nombre de tu API y un optional-string con una breve descripción - Cómo configurar una ruta para usar una clave de API
- Varios esquemas de seguridad para la autenticación
- Extensiones de OpenAPI
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.