Le Azure Function sono un servizio serverless decisamente comodo quando vogliamo scrivere velocemente codice senza doverci preoccupare di tutto quello che sta intorno. Il focus è sul codice, scala in maniera autonoma e tutto l'ambiente è gestito. Anche nella realizzazione di API, quando non sono particolarmente strutturate, sono immediate e l'uso di HttpTrigger ci permette di fornire e di proteggere un'operazione raggiungibile tramite un indirizzo.

Non essendoci tutto lo stack ASP.NET Core, però, la parte di gestione delle richieste e delle risposte è completamente manuale. Questo dà massima flessibilità, ma complica un po' la gestione degli stessi non fornendo alcun supporto alla documentazione delle operazioni esposte. Viene in aiuto però OpenAPI, nato proprio per documentare in JSON le operazioni REST. Possiamo sfruttare fortunatamente questo strumento anche nelle function, grazie a delle estensioni e al supporto di Visual Studio. Quando creiamo una function, infatti, viene proposto di supportare OpenAPI.

Viene creata così una function che oltre all'attributo Function sull'entry point della stessa, è adornata con una serie di attributi del namespace Microsoft.Azure.WebJobs.Extensions.OpenApi.Core.Attributes.

[FunctionName("SendMailFunction")]
[OpenApiOperation(operationId: "Run", tags: new[] { "Mail" })]
[OpenApiParameter(
    name: "id",
    In = ParameterLocation.Query,
    Required = true,
    Type = typeof(string),
    Description = "The *Id* parameter")]

[OpenApiRequestBody(contentType: "application/json", 
    typeof(SendMailRequest),
    Required = true)]

[OpenApiResponseWithBody(statusCode: HttpStatusCode.OK,
    contentType: "application/json",
    bodyType: typeof(SendMailResponse),
    Description = "The OK response")]
public static async Task<IActionResult> Run(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = null)] HttpRequest req,
    ILogger log)

Il loro utilizzo è piuttosto intuitivo. Possiamo descrivere come è fatta la richiesta, la risposta e i parametri in ingresso. Possiamo indicare, nomi, descrizioni, l'obbligatorietà ed utilizzare tipi .NET per lo schema dei tipi complessi.
Avviando il runtime notiamo di conseguenza nuovi endpoint builtin che troveremo poi anche una volta fatto il deployment.

E' disponibile il json in formato Swagger, OpenAPI e anche la UI standard per mostrare e provare la funzione.

Tra gli attributi utili troviamo, infine, OpenApiPropertyDescription, da applicare alle proprietà degli oggetti complessi, OpenApiIgnore per escludere una funzione e OpenApiSecurity per documentare il tipo di sicurezza.