Descripción general de OpenAPI

Cloud Endpoints es compatible con las API que se describen si se usa la versión 2.0 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.

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 la API. Si deseas obtener más información, consulta el Portal de Cloud Endpoints.

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. El documento de OpenAPI de la guía de inicio rápido de Endpoints ilustra esta estructura básica:

    swagger: "2.0"
    info:
      title: "Airport Codes"
      description: "Get the name of an airport from its three-letter IATA code."
      version: "1.0.0"
    # This field will be replaced by the deploy_api.sh script.
    host: "YOUR-PROJECT-ID.appspot.com"
    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, 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?