Panoramica di OpenAPI

Cloud Endpoints supporta le API descritte utilizzando la versione 2.0 di Specifica OpenAPI. L'API può essere implementata utilizzando qualsiasi framework REST disponibile pubblicamente, ad esempio Django o Jersey. Descrivi l'API in un file JSON o YAML denominato OpenAPI di testo. In questa pagina vengono descritti alcuni dei vantaggi dell'utilizzo di OpenAPI, mostra un documento OpenAPI di base e fornisce informazioni aggiuntive per aiutarti a iniziare a utilizzare OpenAPI.

Vantaggi

Uno dei principali vantaggi dell'uso di OpenAPI è la documentazione; una volta avere un documento OpenAPI che descriva l'API, è facile documentazione di riferimento per l'API. Consulta: Portale Cloud Endpoints per ulteriori informazioni.

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

  • Genera librerie client in decine di linguaggi.
  • Generare stub server.
  • Utilizza i progetti per verificare la conformità e generare esempi.

Struttura di base di un documento OpenAPI

Un documento OpenAPI descrive superficie dell'API REST e definisce informazioni quali:

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

Se non hai mai utilizzato OpenAPI, consulta la Struttura di base con Swing che fornisce un documento OpenAPI di esempio (chiamato anche Swagger specifica) e spiega brevemente ogni sezione del file. Il documento OpenAPI dal Guida rapida agli endpoint illustra questa struttura di base:

    swagger: "2.0"
    info:
      title: "Airport Codes"
      description: "Get the name of an airport from its three-letter IATA code."
      version: "1.0.0"
    # This field will be replaced by the deploy_api.sh script.
    host: "YOUR-PROJECT-ID.appspot.com"
    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, il file openapi.yaml dell'esempio 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 Maglia e Primavera in grado di generare un documento OpenAPI dalle annotazioni. C'è anche un plug-in Maven. Per gli utenti Python, flask-swagger potrebbe essere un progetto interessante. svagger-node-express per sviluppatori di nodi.

La community OpenAPI sviluppa continuamente strumenti per facilitare la composizione (e, per alcune lingue, generazione automatica) di documenti OpenAPI. Consulta le Sito web spavaldo per un elenco completo di strumenti e integrazioni.

Passaggi successivi