Descripción general de OpenAPI

Cloud Endpoints 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 JSON o YAML 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

Cloud Endpoints 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, Cloud Endpoints admite todas las versiones de parche de 3.0.

Terminología

En toda la documentación de Cloud Endpoints, OpenAPI 3.x hace referencia a todas las versiones compatibles de OpenAPI 3.

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 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: API_NAME.endpoints.YOUR_PROJECT_ID.cloud.goog
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 es la primera vez que usas OpenAPI, consulta la especificación de OpenAPI, 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
servers:
  - url: https://API_NAME.endpoints.YOUR_PROJECT_ID.cloud.goog
    x-google-endpoint: {}
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, en el archivo openapi.yaml del código de muestra utilizado en los instructivos, se ilustra 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 pueden generar un documento de OpenAPI desde anotaciones. También existe un complemento de Maven. Para los usuarios de Python, flask-swagger puede ser un proyecto interesante, al igual que swagger-node-express para los desarrolladores de Node.

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 el sitio web de Swagger para obtener una lista completa de integraciones y herramientas.

¿Qué sigue?