La documentation Swagger et .NET core

Dans cet article, je vais vous parler d’une problème rencontré avec swagger dans un projet .NET core. Lors de notre développement, nous avions de la documentation sur notre méthodes pour décrire nos actions qui devait se retrouver dans la documentation généré. En local, debug ou release aucun soucis ! Par contre une fois qu’on fait un publish de notre projet … la documentation n’est pas présente ! Voyons comment résoudre ce problème.

PS C:\CoreProjectWithSwagger\CoreProjectWithSwagge > dotnet run -c release

Unhandled Exception: System.IO.FileNotFoundException: Could not find file 'C:\CoreProjectWithSwagger\CoreProjectWithSwagger\bin\release\netc
oreapp1.1\CoreProjectWithSwagger.xml'.

Installation de Swagger dans notre projet

Ce n’est pas le but de cet article, donc en voici un qui vous décrit comment implémenter Swagger dans votre projet .net cotre

C’est par ici !

Récupérer le fichier de documentation

Sur une de nos méthode va par exemple placer de la documentation pour préciser qu’un retour de notre méthode puisse être un code 403. Ce que l’on veut au final, c’est que swagger utilise cette documentation pour la rajouter dans son interface.

        /// <response code="403">Authorization has been denied for this request.</response>
        [HttpGet]
        public IEnumerable<string> Get()
        {
            return new string[] { "value1", "value2" };
        }

Pour au final avoir ce résultat :

La première chose à faire est de faire en sorte que notre projet génère la documentation. Pour se faire, voici les différentes étapes.

Premièrement on va rajouter deux entrée dans notre .csproj (Une pour le mode debug et une autre pour le mode release)

  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'">
    <DocumentationFile>bin\Debug\netcoreapp1.1\CoreProjectWithSwagger.xml</DocumentationFile>
  </PropertyGroup>

  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Release|AnyCPU'">
    <DocumentationFile>bin\Release\netcoreapp1.1\CoreProjectWithSwagger.xml</DocumentationFile>
  </PropertyGroup>

Ces deux propriétés vont donc générer notre documentation XML dans le dossier de build correspondant à notre mode.

Ensuite dans le Startup.cs à l’intérieur de notre méthode ConfigureServices, il faut préciser le chemin vers ce fichier pour que swashbuckle puisse l’utiliser et afficher notre documentation dans l’UI.

            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" });

                // on récupère le chemin vers notre fichier de documentation
                var filePath = Path.Combine(PlatformServices.Default.Application.ApplicationBasePath, "CoreProjectWithSwagger.xml");
                // on passe notre fichier à Swashbuckle pour qu'il puisse l'exploiter
                c.IncludeXmlComments(filePath);
            });

Et c’est tout ! Et bien non … Si on run en l’état, lorsqu’on va afficher notre doc swagger, on va recevoir une erreur comme quoi il n’arrive pas à récupérer le fichier et c’est la qu’il faut rajouter un petit bout de code dans notre .csproj qui va aller rechercher le fichier et le copier correctement au bon endroit.

  <Target Name="PrepublishScript" BeforeTargets="PrepareForPublish">
    <ItemGroup>
      <DocFile Include="bin\$(Configuration)\$(TargetFramework)\*.xml" />
    </ItemGroup>
    <Copy SourceFiles="@(DocFile)" DestinationFolder="$(PublishDir)" SkipUnchangedFiles="false" />
  </Target>

Maintenant, faites votre dotnet publish, puis un run et rendez-vous sur l’adresse /swagger/ . Tadam ! votre documentation est la !

Code du projet

Vous pouvez retrouver le code du projet sur mon github : https://github.com/MatthieuVdh/CoreProjectWithSwagger

No Comments

Post a Comment