Panoramica di OpenAPI

Cloud Endpoints supporta le API descritte utilizzando la versione 2.0 della specifica OpenAPI. L'API può essere implementata utilizzando qualsiasi framework REST disponibile pubblicamente, ad esempio Django o Jersey. Descrivi la tua API in un file JSON o YAML denominato documento OpenAPI. Questa pagina descrive alcuni dei vantaggi dell'utilizzo di OpenAPI, mostra un documento OpenAPI di base e fornisce informazioni aggiuntive per aiutarti a iniziare a utilizzare OpenAPI.

Vantaggi

Uno dei principali vantaggi dell'utilizzo di OpenAPI è la documentazione. Una volta che hai un documento OpenAPI che descrive la tua API, è facile generare la documentazione di riferimento per la tua API. Per ulteriori informazioni, consulta il portale Cloud Endpoints.

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

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

Struttura di base di un documento OpenAPI

Un documento OpenAPI descrive la piattaforma 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 Struttura di base di Swagger, che fornisce un documento OpenAPI di esempio (chiamato anche specifica Swagger) e spiega brevemente ogni sezione del file. Il documento OpenAPI della guida rapida di Endpoints 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 di base, il file openapi.yaml del codice di esempio utilizzato nei tutorial illustra:

Generazione di un documento OpenAPI

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

La community OpenAPI sviluppa continuamente strumenti per facilitare la composizione (e, per alcune lingue, la generazione automatica) dei documenti OpenAPI. Per un elenco completo di strumenti e integrazioni, visita il sito web di Swagger.

Passaggi successivi