Panoramica di OpenAPI

API Gateway 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 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

API Gateway 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, API Gateway supporta tutte le versioni patch 3.0.

Terminologia

Nella documentazione di API Gateway, OpenAPI 3.x si riferisce a tutte le versioni supportate di OpenAPI 3, come descritto in Versioni supportate di OpenAPI.

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 del server
  • Utilizzare 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, dai un'occhiata alla struttura di base di Swagger, che fornisce un documento OpenAPI di esempio (chiamato anche specifica Swagger) e spiega brevemente ogni sezione del file. Il seguente esempio 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: DNS_NAME_OF_DEPLOYED_API
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, dai un'occhiata alla struttura di base di Swagger, 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
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, utilizza il file openapi.yaml per configurare:

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. È disponibile anche un plugin Maven. Per gli sviluppatori Python e Node, OpenAPI.Tools potrebbe essere un progetto interessante.

La community OpenAPI sviluppa continuamente strumenti per facilitare la composizione (e, per alcune lingue, la generazione automatica) dei documenti OpenAPI. Per saperne di più, consulta la specifica OpenAPI.

Passaggi successivi