Panoramica di OpenAPI

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

La tua 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, chiamato 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

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

Supporto delle 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.

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.

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 conformità e 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.

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 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 familiarità con OpenAPI, dai un'occhiata alla specifica OpenAPI, che fornisce un documento OpenAPI di esempio e spiega ogni sezione del file.

Il seguente esempio 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:
  backend:
    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 dell'esempio di codice 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 plugin Maven. Per gli utenti 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