Información general sobre OpenAPI

Cloud Endpoints admite APIs descritas mediante versiones compatibles de la especificación de OpenAPI.

Tu API se puede implementar con cualquier framework REST disponible públicamente, como Django o Jersey.

Describe tu API en un archivo JSON o YAML, que se conoce como 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.

Versiones compatibles de OpenAPI

Cloud Endpoints admite las siguientes versiones de OpenAPI:

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

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

Compatibilidad con versiones de parche

La especificación de OpenAPI indica que las versiones de parche (por ejemplo, 3.0.1 y 3.0.2) solo incluyen correcciones o aclaraciones y no añaden funciones nuevas. Por lo tanto, 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.

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, podrás generar documentación de referencia para ella.

Usar OpenAPI tiene otras ventajas. Por ejemplo, puedes:

  • Genera bibliotecas de cliente en decenas de idiomas.
  • Genera 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.

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 no conoces OpenAPI, consulta el sitio web sobre la 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: 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 no conoces OpenAPI, consulta la especificación de OpenAPI, que incluye un documento de ejemplo y explica cada sección del archivo.

En el siguiente ejemplo se muestra 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, el archivo openapi.yaml del código de ejemplo que se usa en los tutoriales muestra 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 OpenAPI a partir de anotaciones. También hay un plugin de Maven. Para los usuarios de Python, flask-swagger puede ser un proyecto interesante, y swagger-node-express para los desarrolladores de Node.

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

Siguientes pasos