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, come Django o Jersey.

Puoi descrivere l'API in un file 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 OpenAPI supportate

API Gateway 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 della versione 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 di 3.0 e 3.1.

Terminologia

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

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, 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. 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: 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. 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
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, 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. Esiste anche un plug-in Maven. Per gli sviluppatori Python e Node, OpenAPI.Tools potrebbe essere un progetto interessante.

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

Passaggi successivi