Supporto per metadati OpenAPI 2.0 in Funzioni di Azure (anteprima)OpenAPI 2.0 metadata support in Azure Functions (preview)

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.OpenAPI 2.0 (formerly Swagger) metadata support in Azure Functions is a preview feature that you can use to write an OpenAPI 2.0 definition inside a function app. Con l'app per le funzioni è poi possibile ospitare quel file.You can then host that file by using the function app.

I metadati OpenAPI consentono a una funzione che ospita un'API REST di essere usata da una vasta gamma di altri software,OpenAPI metadata allows a function that's hosting a REST API to be consumed by a wide variety of other 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.This software includes Microsoft offerings like PowerApps and the API Apps feature of Azure App Service, third-party developer tools like Postman, and many more packages.

Informazioni di riferimento per gli sviluppatori delle Funzioni di Azure.This is reference information for Azure Functions developers. Se non si ha familiarità con le Funzioni di Azure, iniziare con le seguenti risorse:If you're new to Azure Functions, start with the following resources:

Suggerimento

È consigliabile iniziare con l'esercitazione introduttiva e tornare successivamente a questo documento per approfondire le funzionalità specifiche.We recommend starting with the getting started tutorial and then returning to this document to learn more about specific features.

Abilitare il supporto per la definizione OpenAPIEnable OpenAPI definition support

È possibile configurare tutte le impostazioni OpenAPI nella pagina Definizione API in Funzionalità della piattaforma per l'app per le funzioni.You can configure all OpenAPI settings on the API Definition page in your function app's Platform features.

Per abilitare la generazione di una definizione OpenAPI ospitata e una definizione di avvio rapido, impostare Origine della definizione dell'API su Funzione (anteprima).To enable the generation of a hosted OpenAPI definition and a quickstart definition, set API definition source to Function (Preview). L'URL esterno consente alla funzione di usare una definizione OpenAPI ospitata altrove.External URL allows your function to use an OpenAPI definition that's hosted elsewhere.

Generare una struttura Swagger dai metadati della funzioneGenerate a Swagger skeleton from your function's metadata

Per iniziare a scrivere la prima definizione OpenAPI può essere utile usare un modello.A template can help you start writing your first OpenAPI definition. 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.The definition template feature creates a sparse OpenAPI definition by using all the metadata in the function.json file for each of your HTTP trigger functions. Le altre informazioni relative all'API, ad esempio i modelli di richiesta e risposta, devono essere inserite nella specifica OpenAPI.You'll need to fill in more information about your API from the OpenAPI specification, such as request and response templates.

Per istruzioni dettagliate, vedere l'esercitazione introduttiva.For step-by-step instructions, see the getting started tutorial.

Modelli disponibiliAvailable templates

NomeName DescrizioneDescription
Definizione generataGenerated Definition Una definizione OpenAPI con la quantità massima di informazioni deducibili dai metadati esistenti della funzione.An OpenAPI definition with the maximum amount of information that can be inferred from the function's existing metadata.

Metadati inclusi nella definizione generataIncluded metadata in the generated definition

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.The following table represents the Azure portal settings and corresponding data in function.json as it is mapped to the generated Swagger skeleton.

Swagger.jsonSwagger.json Interfaccia utente del portalePortal UI Function.jsonFunction.json
HostHost Impostazioni dell'app per le funzioni > Impostazioni del servizio app > Panoramica > URLFunction app settings > App Service settings > Overview > URL Non presenteNot present
PercorsiPaths Integrazione > Metodi HTTP selezionatiIntegrate > Selected HTTP methods Associazioni: RouteBindings: Route
Elemento del percorsoPath Item Integrazione > Modello di routeIntegrate > Route template Associazioni: MetodiBindings: Methods
SicurezzaSecurity ChiaviKeys Non presenteNot present
operationIDoperationID Route + Verbi consentitiRoute + Allowed verbs Route + verbi consentitiRoute + Allowed Verbs

*L'ID dell'operazione è necessario soltanto per l'integrazione di PowerApps e Flow.*The operation ID is required only for integrating with PowerApps and Flow.

Nota

L'estensione x-ms-summary indica il nome visualizzato in App per la logica, PowerApps e Flow.The x-ms-summary extension provides a display name in Logic Apps, PowerApps, and Flow.

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

Usare CI/CD per impostare una definizione dell'APIUse CI/CD to set an API definition

È 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.You must enable API definition hosting in the portal before you enable source control to modify your API definition from source control. Seguire queste istruzioni:Follow these instructions:

  1. Passare a Definizione API (anteprima) nelle impostazioni dell'app per le funzioni.Browse to API Definition (preview) in your function app settings.
    1. Impostare Origine della definizione dell'API su Funzione.Set API definition source to Function.
    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.Click Generate API definition template and then Save to create a template definition for modifying later.
    3. Prendere nota dell'URL di definizione dell'API e della chiave.Note your API definition URL and key.
  2. Impostare l'integrazione continuata e la distribuzione continua (CI/CD).Set up continuous integration/continuous deployment (CI/CD).
  3. Modificare il file swagger.json nel controllo del codice sorgente in \site\wwwroot.azurefunctions\swagger\swagger.json.Modify swagger.json in source control at \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.Now, changes to swagger.json in your repository are hosted by your function app at the API definition URL and key that you noted in step 1.c.

Passaggi successiviNext steps