Supporto per metadati OpenAPI 2.0 in Funzioni di Azure (anteprima)

Il supporto per metadati OpenAPI 2.0 (in precedenza Swagger) in Funzioni di Azure è una funzionalità di anteprima che consente di scrivere una definizione di OpenAPI 2.0 all'interno di un'app per le funzioni. Con l'app per le funzioni è poi possibile ospitare quel file.

I metadati OpenAPI consentono a una funzione che ospita un'API REST di essere usata da una vasta gamma di altri software, tra cui le offerte Microsoft, quali PowerApps e la funzionalità app per le api di Servizio app di Azure , gli strumenti di sviluppo di terze parti come Postman e molti altri pacchetti.

Informazioni di riferimento per gli sviluppatori delle Funzioni di Azure. Se non si ha familiarità con le Funzioni di Azure, iniziare con le seguenti risorse:

Suggerimento

È consigliabile iniziare con l'esercitazione introduttiva e tornare successivamente a questo documento per approfondire le funzionalità specifiche.

Abilitare il supporto per la definizione OpenAPI

È possibile configurare tutte le impostazioni OpenAPI nella pagina Definizione API (anteprima) delle impostazioni dell'app per le funzioni.

Per abilitare la generazione di una definizione di OpenAPI ospitata e una definizione di avvio rapido, impostare Origine della definizione dell'API su Funzione. L'URL esterno consente alla funzione di usare una definizione OpenAPI ospitata altrove.

Generare una struttura Swagger dai metadati della funzione

Per iniziare a scrivere la prima definizione OpenAPI può essere utile usare un modello. La funzione del modello di definizione crea una definizione OpenAPI di tipo sparse usando tutti i metadati contenuti nel file function.json per ognuna delle funzioni trigger HTTP. Le altre informazioni relative all'API, ad esempio i modelli di richiesta e risposta, devono essere inserite nella specifica OpenAPI.

Per istruzioni dettagliate, vedere l'esercitazione introduttiva.

Modelli disponibili

Nome Descrizione
Definizione generata Una definizione OpenAPI con la quantità massima di informazioni deducibili dai metadati esistenti della funzione.

Metadati inclusi nella definizione generata

La tabella seguente include le impostazioni del portale di Azure e i dati corrispondenti in function.json, dei quali viene eseguito il mapping nella struttura Swagger generata.

Swagger.json Interfaccia utente del portale Function.json
Host Impostazioni dell'app per le funzioni > Impostazioni del servizio app > Panoramica > URL Non presente
Percorsi Integrazione > Metodi HTTP selezionati Associazioni: Route
Elemento del percorso Integrazione > Modello di route Associazioni: Metodi
Sicurezza Chiavi Non presente
operationID* Route + Verbi consentiti Route + verbi consentiti

*L'ID dell'operazione è necessario soltanto per l'integrazione di PowerApps e Flow.

Nota

L'estensione x-ms-summary indica il nome visualizzato in App per la logica, PowerApps e Flow.

Per altre informazioni, vedere Customize your Swagger definition for PowerApps (Personalizzare la definizione Swagger per PowerApps).

Usare CI/CD per impostare una definizione dell'API

È necessario abilitare l'hosting di definizione dell'API nel portale prima di attivare il controllo del codice sorgente per modificare la definizione dal codice sorgente. Seguire queste istruzioni:

  1. Passare a Definizione API (anteprima) nelle impostazioni dell'app per le funzioni.
    1. Impostare Origine della definizione dell'API su Funzione.
    2. Fare clic su Genera modello di definizione dell'API e su Salva per creare una definizione del modello da modificare in un secondo momento.
    3. Prendere nota dell'URL di definizione dell'API e della chiave.
  2. Impostare l'integrazione continuata e la distribuzione continua (CI/CD).
  3. Modificare il file swagger.json nel controllo del codice sorgente in \site\wwwroot.azurefunctions\swagger\swagger.json.

A questo punto, le modifiche apportate al file swagger.json nell'archivio sono ospitate dall'app per le funzioni con l'URL di definizione dell'API e la chiave annotate nel passaggio 1.c.

Passaggi successivi