Panoramica di OpenAPI

Cloud Endpoints supporta le API descritte con la versione 2.0 della specifica OpenAPI. Puoi implementare l'API utilizzando qualsiasi framework REST disponibile pubblicamente come Django o Jersey. Descrivi l'API in un file JSON o YAML denominato documento OpenAPI. In questa pagina vengono descritti alcuni dei vantaggi offerti dall'utilizzo di OpenAPI, viene mostrato un documento OpenAPI di base e vengono fornite informazioni aggiuntive per iniziare a utilizzare OpenAPI.

Vantaggi

Uno dei principali vantaggi dell'utilizzo di OpenAPI è la documentazione; una volta creato un documento OpenAPI che descrive l'API, è facile generare una documentazione di riferimento per l'API. Per ulteriori informazioni, visita il portale Cloud Endpoints.

L'utilizzo di OpenAPI offre altri vantaggi. Ad esempio, puoi:

  • Genera librerie client in decine di lingue.
  • Genera stub server.
  • Utilizza i progetti per verificare la tua conformità e per generare campioni.

Struttura di base di un documento OpenAPI

Un documento OpenAPI descrive la superficie della tua API REST e definisce informazioni quali:

  • Il nome e la descrizione dell'API.
  • I singoli endpoint (percorsi) nell'API.
  • Come vengono autenticati i chiamanti.

Se non hai mai utilizzato OpenAPI, dai un'occhiata al sito web di struttura di base di Swagger, che fornisce un documento OpenAPI di esempio (noto anche come specifica Swagger) che spiega brevemente ogni sezione del file. Il documento OpenAPI della guida rapida agli endpoint illustra questa struttura di base:

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

Oltre alla struttura base, il file openapi.yaml del codice di esempio utilizzato nei tutorial illustra:

Generazione di un documento OpenAPI

A seconda della lingua utilizzata, potresti essere in grado di generare un documento OpenAPI. In Java, esistono progetti open source sia per Jersey che per Spring che possono generare un documento OpenAPI dalle annotazioni. È inoltre disponibile un plug-in Maven. Per gli utenti Python, flask-swagger potrebbe essere un progetto interessante e swagger-node-express per gli sviluppatori di nodi.

La community di OpenAPI sviluppa continuamente strumenti per la creazione di documenti OpenAPI (e, per alcuni linguaggi, generazione automatica). Per un elenco completo di strumenti e integrazioni, consulta il sito web di Swagger.

Passaggi successivi