Información general sobre OpenAPI

Cloud Endpoints admite APIs descritas con la versión 2.0 de la especificación 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.

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:

  • 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.

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. El documento OpenAPI de la guía de inicio de Endpoints muestra 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, 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