Panoramica di OpenAPI

Cloud Endpoints supporta le API descritte utilizzando versioni supportate della specifica OpenAPI.

La tua API può essere implementata utilizzando qualsiasi framework REST disponibile pubblicamente, come 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 ulteriori informazioni per aiutarti a iniziare a utilizzare OpenAPI.

Versioni di OpenAPI supportate

Cloud Endpoints supporta le seguenti versioni di OpenAPI:

  1. OpenAPI 2.0 (in precedenza Swagger)
  2. OpenAPI 3.0.x
  3. OpenAPI 3.1.x

Le specifiche ufficiali per ogni versione sono disponibili presso l'OpenAPI Initiative.

Supporto per le versioni patch

La specifica OpenAPI indica che le versioni patch (ad es. 3.0.1, 3.0.2) introducono solo correzioni o chiarimenti e non aggiungono nuove funzionalità. Di conseguenza, Cloud Endpoints supporta tutte le versioni patch di 3.0 e 3.1.

Terminologia

Nella documentazione di Cloud Endpoints, OpenAPI 3.x si riferisce a tutte le versioni supportate di OpenAPI 3.

Vantaggi

Uno dei principali vantaggi dell'utilizzo di OpenAPI è la documentazione: una volta che hai un documento OpenAPI che descrive la tua API, puoi generare la documentazione di riferimento per la tua API.

Ci sono altri vantaggi nell'utilizzo di OpenAPI. Ad esempio, puoi:

  • Generare librerie client in decine di lingue.
  • Generare stub del server.
  • Utilizzare i progetti per verificare la conformità e generare esempi.

Struttura di base di un documento OpenAPI

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

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

La struttura del documento OpenAPI dipende dalla versione di OpenAPI che utilizzi. Gli esempi seguenti descrivono la struttura di OpenAPI 2.0 e OpenAPI 3.x.

OpenAPI 2.0

Se non hai mai utilizzato OpenAPI, consulta il sito web della struttura di base di Swagger, che fornisce un documento OpenAPI di esempio (chiamato anche specifica Swagger) e spiega brevemente ogni sezione del file. L'esempio seguente illustra questa struttura di base:

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

Se non hai mai utilizzato OpenAPI, consulta la specifica OpenAPI, che fornisce un documento OpenAPI di esempio e spiega ogni sezione del file.

L'esempio seguente illustra questa struttura di base:

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:
  backends:
    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

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

Generare 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 che per Spring che possono generare un documento OpenAPI dalle annotazioni. Esiste anche un plug-in Maven. Per gli utenti Python, flask-swagger potrebbe essere un progetto interessante, così come swagger-node-express per gli sviluppatori Node.

La community di 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, consulta il sito web di Swagger.

Passaggi successivi