Creazione di metadati OpenAPI 2.0 (Swagger) per un'app per le funzioni (anteprima)

Questo documento contiene la procedura dettagliata per la creazione di una definizione OpenAPI per una semplice API ospitata in Funzioni di Azure.

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:

Definizione di OpenAPI (Swagger)

Swagger Metadata è un file che definisce le funzionalità e le modalità di funzionamento dell'API e consente a una funzione che ospita un'API REST di essere usata con un'ampia gamma di altri prodotti software. Offerte Microsoft quali PowerApps e App per le API, nonché strumenti di sviluppatori di terze parti come Postman e altri pacchetti consentono di usare l'API con una definizione Swagger.

Creazione di una funzione con una API semplice

Per creare una definizione OpenAPI, è innanzitutto necessario creare una funzione con un'API semplice. Se si dispone già di un'API ospitata in un'app per le funzioni, è possibile passare direttamente alla sezione successiva.

  1. Creare una nuova app per le funzioni.
    1. Portale di Azure > + New > Eseguire una ricerca per "App per le funzioni"
  2. Creare una nuova funzione trigger HTTP all'interno della nuova app per le funzioni
    1. La funzione è già popolata con codice che definisce un'API REST semplice.
    2. Ogni stringa passata alla funzione come parametro di query o nel corpo viene restituita come "Hello {input}"
  3. Passare alla scheda Integrate della nuova funzione trigger HTTP
    1. Attivare/disattivare Allowed HTTP methods su Selected methods
    2. In Selected HTTP methods deselezionare ogni verbo tranne POST. Metodi HTTP selezionati
    3. Questo passaggio semplifica la definizione dell'API in un secondo momento.

Abilitazione del supporto per la definizione API

  1. Passare a your function name > API Definition (preview)
  2. Impostare API Definition Source su Function
    1. Questo passaggio consente a una suite di opzioni di OpenAPI per l'app per le funzioni, incluso un endpoint, di ospitare un file OpenAPI dal dominio dell'app, una copia inline dell'editor di OpenAPIe un generatore di definizioni di avvio rapido. Definizioni attivate

Creazione della definizione dell'API da un modello

  1. Fare clic suGenerate API Definition template.
    1. Questo passaggio esegue la scansione dell'app per le funzioni per le funzioni HTTP trigger e usa le informazioni contenute in functions.json per generare un documento OpenAPI.
  2. Aggiungere un oggetto operation a paths: /api/yourfunctionroute post:

    1. Il documento OpenAPI di avvio rapido è una struttura di un documento OpenAPI completo. Sono tuttavia necessari altri metadati affinché si tratti di una definizione OpenAPI completa, ad esempio oggetti operazione e modelli di risposta.
    2. L'oggetto operazione di esempio include una sezione produce/usa, un oggetto parametro e un oggetto risposta.
       post:
         operationId: /api/yourfunctionroute/post
         consumes: [application/json]
         produces: [application/json]
         parameters:
           - name: name
             in: body
             description: Your name
             x-ms-summary: Your name
             required: true
             schema:
               type: object
               properties:
                 name:
                   type: string
         description: >-
           Replace with Operation Object
           #http://swagger.io/specification/#operationObject
         responses:
           '200':
             description: A Greeting
             x-ms-summary: Your name
             schema:
               type: string
         security:
           - apikeyQuery: []
    
Nota

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

Per altre informazioni, leggere Personalizzare la definizione Swagger per PowerApps.

  1. Fare clic su save per salvare le modifiche Aggiunta di definizioni del modello

Utilizzo della definizione dell'API

  1. Copiare l'API definition URL e incollarlo in una nuova scheda del browser per visualizzare il documento OpenAPI non elaborato.
  2. Tale URL consente di importare il documento OpenAPI in qualsiasi strumento per finalità di test e integrazione.
    1. Molte risorse di Azure sono in grado di importare automaticamente il documento OpenAPI usando l'URL di definizione API salvato nelle impostazioni dell'app per le funzioni. Nel codice sorgente della definizione API Function, tale URL è già stato aggiornato.

Usare l'interfaccia utente di Swagger per testare la definizione dell'API

Esistono strumenti di test integrati nell'interfaccia utente dell'editor della definizione API. Aggiungere la chiave API e quindi usare il pulsante Try this operation in ogni metodo. Lo strumento usa la definizione API per formattare le richieste; se le risposte conseguenti hanno esito positivo, la definizione è corretta.

Passaggi:

  1. Copiare la chiave API della funzione
    1. La chiave API è reperibile nella funzione trigger HTTP in function name > Keys > Function Keys tasto funzione
  2. Passare alla pagina API Definition (preview).
    1. Fare clic su Authenticate e aggiungere la chiave API della funzione all'oggetto security, nella parte superiore. Chiave OpenAPI
  3. Selezionare /api/yourfunctionroute > POST
  4. Fare clic su Try it out e immettere un nome per il test
  5. Nel test di definizione dell'API di Pretty verrà visualizzato l'esito positivo

Passaggi successivi