Panoramica di OpenAPI

API Gateway supporta le API descritte utilizzando la specifica OpenAPI, versione 2.0. L'API può essere implementata utilizzando qualsiasi framework REST disponibile pubblicamente come 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.

Vantaggi

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

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

  • Genera librerie client in decine di linguaggi
  • Generare stub del 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 come:

  • Il nome e la descrizione dell'API
  • I singoli endpoint (percorsi) nell'API
  • Modalità di autenticazione dei chiamanti

Se non hai mai utilizzato OpenAPI, dai un'occhiata al sito web Swagger Basic Infrastructure, 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."

Oltre alla struttura di base, utilizza il file openapi.yaml per configurare:

Generazione di un documento OpenAPI

A seconda del linguaggio che utilizzi, potresti essere in grado di generare un documento OpenAPI. In Java esistono progetti open source sia per Jersey che per Spring in grado di generare un documento OpenAPI dalle annotazioni. È disponibile anche un plug-in Maven. Per gli sviluppatori Python e Node, OpenAPI.Tools potrebbe essere un progetto interessante.

La community OpenAPI sviluppa continuamente strumenti per semplificare la composizione (e, per alcuni linguaggi, la generazione automatica) dei documenti OpenAPI. Consulta la specifica OpenAPI per ulteriori informazioni.

Passaggi successivi