Fermer

mai 9, 2022

Activation des spécifications OpenAPI pour la fonction Azure

Activation des spécifications OpenAPI pour la fonction Azure


Qu’est-ce qu’un document OpenAPI ?

Selon Swagger, OpenAPI Document est un document (ou un ensemble de documents) qui définit ou décrit une API. Une définition OpenAPI utilise et se conforme à la spécification OpenAPI.

« La spécification OpenAPI (OAS) définit une interface standard, indépendante du langage, pour les API RESTful, qui permet aux humains et aux ordinateurs de découvrir et de comprendre les capacités du service sans accéder au code source, à la documentation ou via l’inspection du trafic réseau. Lorsqu’il est correctement défini, un consommateur peut comprendre et interagir avec le service distant avec un minimum de logique d’implémentation.

Une définition OpenAPI peut ensuite être utilisée par des outils de génération de documentation pour afficher l’API, des outils de génération de code pour générer des serveurs et des clients dans divers langages de programmation, des outils de test et de nombreux autres cas d’utilisation.

En novembre 2021, Azure Functions a fourni une assistance pour ajouter un document OpenAPI et des définitions aux fonctions déclenchées par la méthode HTTP. Cela a été rendu possible par l’utilisation du package NuGet Microsoft.Azure.WebJobs.Extensions.OpenApi . Le package a été initialement créé en tant que projet communautaire qui a ensuite été pris en charge et maintenu en tant que projet officiel par l’équipe Microsoft.

Pourquoi avons-nous besoin d’un document OpenAPI ?

Lorsque les API exposent ou fournissent un document OpenAPI, il peut être utilisé pour en savoir plus sur les opérations de l’API, ainsi que sur les paramètres de demande et les paramètres de réponse pris en charge par l’API. En bref, il sert de documentation pour l’API permettant aux intégrateurs tiers et autres développeurs d’utiliser facilement les méthodes de l’API. Cela permet de réduire les conversations autour de la nécessité de trouver comment utiliser les API.

En utilisant un document OpenAPI, nous pouvons demander à l’équipe de test et aux développeurs tiers qui utilisent notre fonction d’obtenir un aperçu des méthodes prises en charge dans notre fonction, le schéma de demande, le schéma de réponse, le format du message d’erreur et un exemple de demande et de réponse. message. De cette façon, les équipes externes et l’équipe de test n’ont pas à dépendre de l’équipe de développement pour initier leur part de travail. OpenAPI Document fournit également un document auto-explicatif pour comprendre les différentes opérations prises en charge par l’API et il n’est pas nécessaire que l’équipe de développement passe du temps en plus à rédiger des documentations expliquant les méthodes de l’API.

Comment ajoutons-nous OpenAPI Document ?

L’ajout d’une spécification de document OpenAPI à Azure Function est simple. Nous allons commencer par créer une fonction Azure qui utilise HTTP comme déclencheur et utiliser le niveau d’autorisation comme fonction.

Dans Visual Studio 2022, nous pouvons désormais choisir le modèle en tant que déclencheur Http avec OpenAPI.

Createazurefunction

Modèle de projet de fonction Azure Visual Studio 2022

Au moment d’écrire ces lignes, il n’est plus nécessaire d’ajouter manuellement le package Microsoft.Azure.WebJobs.Extensions.OpenApi NuGet au projet Functions. Le package est installé par défaut via le modèle. Maintenant que nous avons créé notre premier projet en utilisant le modèle par défaut, comprenons quelques concepts clés.

[FunctionName("Function1")]
[OpenApiOperation(operationId: "Run", tags: new[] { "name" })]
[OpenApiSecurity("function_key", SecuritySchemeType.ApiKey, Name = "code", In = OpenApiSecurityLocationType.Query)]
[OpenApiParameter(name: "name", In = ParameterLocation.Query, Required = true, Type = typeof(string), Description = "The **Name** parameter")]
[OpenApiResponseWithBody(statusCode: HttpStatusCode.OK, contentType: "text/plain", bodyType: typeof(string), Description = "The OK response")]
public async Task<IActionResult> Run(
    [HttpTrigger(AuthorizationLevel.Function, "get", "post", Route = null)] HttpRequest req)
{
    _logger.LogInformation("C# HTTP trigger function processed a request.");

    string name = req.Query["name"];

    string requestBody = await new StreamReader(req.Body).ReadToEndAsync();
    dynamic data = JsonConvert.DeserializeObject(requestBody);
    name = name ?? data?.name;

    string responseMessage = string.IsNullOrEmpty(name)
        ? "This HTTP triggered function executed successfully. Pass a name in the query string or in the request body for a personalized response."
        : $"Hello, {name}. This HTTP triggered function executed successfully.";

    return new OkObjectResult(responseMessage);
}

Si nous remarquons le code généré par le modèle initial, nous trouverons de nouveaux attributs commençant par OpenApi sur notre Function. Ces attributs contrôlent ce qui est généré dans le cadre de la spécification de document OpenAPI. Pour plus de détails sur les sous-attributs, vous pouvez consulter la section Références.

Vous trouverez ci-dessous les attributs clés que nous devons examiner.

  • OpenApiOperationOpenApiOperation – Cela correspond à «Operation Object» de la spécification OpenAPI.
  • OpenApiResponseWithBody – Cela correspond à « Responses Object » de la spécification OpenAPI.
  • OpenApiParameterOpenApiParameter – Cela correspond à « Parameter Object » de la spécification OpenAPI.
  • OpenApiSecurity – Cela correspond à « Security Scheme Object » de la spécification OpenAPI.

Nous ne créerons pas souvent des fonctions qui transmettraient des paramètres dans la chaîne de requête de l’URL de la fonction.

Il existe des situations où nous devons envoyer un objet de requête au format JSON à Function et nous attendons généralement une réponse au format JSON. Le modèle par défaut est valable pour les fonctions appelées à l’aide d’un paramètre dans la chaîne de requête.

Voyons maintenant comment nous pouvons mettre à jour la fonction pour répondre à notre exigence d’accepter une demande et de renvoyer une réponse au format JSON. Continuons et construisons notre fonction fictionnelle.

Dans le cadre de notre fonction, nous allons continuer et créer deux entités – BookRequest et BookResponse.

   [OpenApiExample(typeof(BookRequestExample))]
    public class BookRequest
    {
        /// <summary>The name of the book</summary>
        [OpenApiProperty]
        public string Name { get; set; }

        /// <summary>The description of the book</summary>
        [OpenApiProperty]
        public string Description { get; set; }
    }

    public class BookRequestExample : OpenApiExample<BookRequest>
    {
        public override IOpenApiExample<BookRequest> Build(NamingStrategy namingStrategy = null)
        {

           this.Examples.Add(
                OpenApiExampleResolver.Resolve(
                    "BookRequestExample",
                    new BookRequest()
                    {
                       Name = "Sample Book",
                       Description = "This is a great book on learning Azure Functions"
                    },
                    namingStrategy
                ));

            return this;
        }
    }
[OpenApiExample(typeof(BookResponseExample))] public class BookResponse { /// <summary> /// The name of the book /// </summary> [OpenApiProperty] public string Name { get; set; } /// <summary> /// The Id of the Book in Guid Format /// </summary> [OpenApiProperty] public Guid BookId { get; set; } /// <summary> /// The description of the book /// </summary> [OpenApiProperty] public string Description { get; set; } } public class BookResponseExample : OpenApiExample<BookResponse> { public override IOpenApiExample<BookResponse> Build(NamingStrategy namingStrategy = null) { this.Examples.Add( OpenApiExampleResolver.Resolve( "BookResponseExample", new BookResponse() { Name = "Sample Book", Description = "This is a great book on learning Azure Functions", BookId = new Guid() }, namingStrategy )); return this; } }

Si nous remarquons le code ci-dessus, nous utilisons deux attributs – OpenApiProperty et OpenApiExample.

  • OpenApiPropertyOpenApiProperty – Cela correspond à l’objet de paramètre de la spécification OpenAPI. Chaque champ de notre classe aura l’attribut OpenApiProperty.
  • OpenApiExemple – Nous utilisons l’attribut OpenApiExample pour mapper l’exemple d’exemple avec BookRequest et BookResponse.

La classe Example doit remplacer la méthode Build. En utilisant OpenApiExampleResolver, nous mappons la classe Example avec une réponse d’exemple valide.

Notre fonction modifiée ressemblera à l’extrait de code ci-dessous.

[FunctionName("Function1")]
[OpenApiOperation(operationId: "Run", tags: new[] { "run" })]
[OpenApiSecurity("function_key", SecuritySchemeType.ApiKey, Name = "code", In = OpenApiSecurityLocationType.Query)]        
[OpenApiRequestBody(contentType: "application/json; charset=utf-8", bodyType: typeof(BookRequest), Description = "Sample Book Request", Required = true)]
[OpenApiResponseWithBody(statusCode: HttpStatusCode.OK, contentType: "application/json; charset=utf-8", bodyType: typeof(BookResponse), Description = "The OK response")]
public async Task<IActionResult> Run(
    [HttpTrigger(AuthorizationLevel.Anonymous, "post", Route = null)] HttpRequest req)
{
    _logger.LogInformation("C# HTTP trigger function processed a request.");
    string requestBody = await new StreamReader(req.Body).ReadToEndAsync();
    var receivedRequest = JsonConvert.DeserializeObject<BookRequest>(requestBody);

    var receivedBook = new BookResponse();
    receivedBook.Name = receivedRequest.Name;
    receivedBook.Description = receivedRequest.Description;
    receivedBook.BookId = System.Guid.NewGuid();
    var result = JsonConvert.SerializeObject(receivedBook, Formatting.None);
    return new OkObjectResult(result);
}

Nous avons introduit un nouvel attribut qui est OpenApiRequestBody. Cela correspond à « Request Body Object » de la spécification OpenAPI.

Continuons et construisons et fonction et exécutons la fonction localement. En cas de construction réussie, nous devrions être en mesure de voir la fenêtre de la console Azure Functions avec l’URL qui peut être utilisée pour appeler la fonction.

Fenêtre de console de fonction AzureAzurefunctionconsolewindow

Nous devrions pouvoir accéder à l’interface utilisateur Swagger et à OpenApiDocument en utilisant l’URL ci-dessous.

RenderOpenApiDocument – ​​http://localhost:7071/api/openapi/1.0

RenderSwaggerUI – http://localhost:7071/api/swagger/ui

Swagger de document OpenAPI

De cette façon, nous pouvons exposer les opérations de notre fonction en utilisant OpenAPI Document. Nous pouvons voir l’opération « exécuter » et les champs d’objets de requête et d’objet de réponse avec un exemple d’exemple. Nous pouvons étendre l’opération « exécuter » et effectuer un test à l’aide de l’interface utilisateur Swagger.

Openapidocumentoperationrun

Le document OpenAPI fonctionne parfaitement bien lorsque les objets de demande et de réponse sont simples.

En écrivant ce blog, j’ai remarqué que la génération de documents OpenAPI a actuellement certains problèmes lorsque les objets de requête utilisent des classes imbriquées ou un tableau de type BookRequest. Je pense que cela sera corrigé dans une future version de l’équipe Functions.

L’exemple de code pour cette fonction se trouve dans le référentiel ci-dessous.

https://github.com/baskarmib/AzureFunctionOpenAPISample

Références-

https://swagger.io/specification/

https://techcommunity.microsoft.com/t5/apps-on-azure-blog/general-availability-of-azure-functions-openapi-extension/ba-p/2931231

https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/concepts/attributes/

Pourquoi performant ?

Nous avons aidé des clients de tous les secteurs à développer des solutions stratégiques et à accélérer des projets cloud innovants. En tant que fournisseur de solutions Azure Direct Cloud (CSP) certifié, nous vous aidons à stimuler l’innovation en fournissant une assistance pour maintenir vos opérations Microsoft Azure en cours d’exécution.

Que votre équipe informatique manque de certaines compétences ou ait simplement besoin d’assistance pour servir une grande entreprise, nous sommes là pour vous aider. Notre expertise et notre support mondial complet vous aideront à tirer le meilleur parti des riches fonctionnalités d’Azure.

Contactez notre équipe pour apprendre plus.

A propos de l’auteur

Baskar travaille dans l’industrie informatique depuis 14 ans au service de clients dans différents domaines tels que la santé, l’assurance et l’espace pharmaceutique. Il a joué divers rôles, commençant en tant que développeur et progressant vers des postes de responsable technique et d’architecte d’applications dans des missions et des engagements précédents avant de rejoindre Perficient. Chez Perficient, Baskar Rao travaille en tant qu’architecte de solutions dans Azure Practice sous Microsoft Business Unit. Vous pouvez le trouver en train de parler lors de rencontres et d’événements de la communauté des développeurs et d’organiser une conférence annuelle en dehors du travail.

Plus de cet auteur






Source link