Cloud Endpoints supporta le API descritte utilizzando la versione 2.0 della specifica OpenAPI.
L'API può essere implementata utilizzando qualsiasi framework REST disponibile pubblicamente come
Django o Jersey.
Descrivi la tua API in un file JSON
o 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.
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. Per ulteriori informazioni, consulta il portale Cloud Endpoints.
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 dell'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. Il documento OpenAPI della guida rapida di 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
del codice campione utilizzato nei tutorial illustra:
- Come configurare un percorso per utilizzare una chiave API.
- Vari schemi di sicurezza per l'autenticazione.
- Estensioni OpenAPI disponibili per le API Endpoints.
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 utenti Python, flask-swagger potrebbe essere un progetto interessante e swagger-node-express per gli sviluppatori di Node.
La community OpenAPI sviluppa continuamente strumenti per semplificare la composizione (e, per alcuni linguaggi, la generazione automatica) dei documenti OpenAPI. Consulta il sito web di Swagger per un elenco completo di strumenti e integrazioni.
Passaggi successivi
- Estensioni OpenAPI
- Funzionalità OpenAPI non supportate
- Configurazione di Endpoints
- Deployment della configurazione di Endpoints