Blog de Hinault Romaric (.NET Core, ASP.NET Core, Azure, DevOps)

Swagger offre des outils permettant de générer la documentation pour son API Web. Il offre également une interface permettant d'explorer et tester les différentes opérations offertes par le service.

J’ai déjà écrit une série de billets de blog sur le sujet, dont vous trouverez ci-dessous :

• Documenter sa Web API ASP.NET Core avec Swagger ;
• Comprendre la spécification OpenAPI (Swagger) et utiliser Swagger Editor ;
• Aller plus loin avec la configuration de Swagger dans une Web API ASP.NET Core.

Dans ce billet de blog, nous verrons comment customiser l’interface de SwaggerUI.

Plusieurs options sont offertes à vous pour modifier l’interface de SwaggerUI afin qu’elle corresponde, par exemple, à la charte graphique de votre entreprise ou de vos applications. Vous pouvez notamment :

• injecter des feuilles de style CSS ;
• injecter du code JavaScript ;
• ou encore définir votre propre page index.

I - Utiliser vos scripts personnalisés pour customiser l’interface de SwaggerUI

Nous allons apporter quelques modifications à l’interface de SwaggerUI en utilisant notre propre fichier CSS. Pour le faire, nous allons dans un premier temps créer un dossier wwwroot à la racine de notre application, ensuite créer dans celui-ci un dossier swagger-ui, puis un dossier css dans le dossier swagger-ui. Dans le dossier css, nous allons créer le fichier custom.css, avec le contenu suivant :

Code css :

Sélectionner tout - Visualiser dans une fenêtre à part

1
2
3
4
5
6
7
8
9
10
11
12
.swagger-section #header {
    border-bottom: 1px solid #000000;
    font-style: normal;
    font-weight: 400;
    background-color: cornflowerblue;
}
.swagger-section #select_document {
     background: blueviolet;
}
.logo__title {
    display: none;
}

Pour que le contenu statique (CSS, image, JavaScript, HTML, etc.) soit rendu dans nos pages Web, nous devons configurer notre application pour prendre en charge cela. Pour le faire, nous devons modifier la méthode Configure() du fichier Startup.cs pour ajouter le middleware permettant le support des fichiers statistiques :

Code c# :

Sélectionner tout - Visualiser dans une fenêtre à part

app.UseStaticFiles();

Si vous utilisez une version inférieure à ASP.NET Core 2.0, vous devez installer le package Microsoft.AspNetCore.StaticFiles.

Une fois cela fait, nous allons injecter le fichier CSS, en référençant son chemin relatif dans les options, lors de la configuration du middleware pour SwaggerUI :

Code c# :

Sélectionner tout - Visualiser dans une fenêtre à part

1
2
3
4
5
6
7
  app.UseSwaggerUI(c =>
             {
               c.SwaggerEndpoint("/swagger/v1/swagger.json", "SwaggerDemo v1");
                c.SwaggerEndpoint("/swagger/v2/swagger.json", "SwaggerDemo v2");
 
                 c.InjectStylesheet("/swagger-ui/css/custom.css");
             });

Une fois l’application en cours d’exécution, en accédant à la page de SwaggerUI, vous allez remarquer que la couleur du bandeau d’entête, ainsi que la couleur de la liste déroulante de sélection de la version de l’API ont changé :

II – Modifier la page index de swagger-ui

Si vous avez des besoins beaucoup plus avancés, vous pouvez récupérer les fichiers source de swagger-ui, les intégrer à votre application et apporter les modifications nécessaires.

En effet, swagger-ui se résume en un fichier index.html et de fichiers JavaScript, CSS et des images. Le code source du projet est disponible sur GitHub à l’adresse suivante : https://github.com/swagger-api/swagger-ui/tree/2.x.

Pour customiser l’interface de swagger-ui dans votre application, vous devez dans un premier temps télécharger le code source du projet sur son GitHub. Ensuite, vous allez copier le contenu du répertoire « dist » dans le répertoire « wwwroot/swagger-ui » de votre application.

Pour apporter des changements à l’IU, vous devez simplement éditer le fichier index.html. Nous allons par exemple modifier ce dernier pour utiliser le script custom.css ci-dessus. Nous allons simplement référencer ce dernier dans le fichier index.html :

Code html :

Sélectionner tout - Visualiser dans une fenêtre à part

<link href='css/custom.css' media='screen' rel='stylesheet' type='text/css' />

Ensuite, nous allons changer la langue de l’IU pour utiliser le français. Pour cela, nous allons ajouter les lignes de code suivantes :

Code html :

Sélectionner tout - Visualiser dans une fenêtre à part

1
2
3
 
  <script src='lang/translator.js' type='text/javascript'></script> 
  <script src='lang/fr.js' type='text/javascript'></script>

Pour information, swagger UI embarque des fichiers de localisation pour une dizaine de langues. Ces derniers sont contenus dans le dossier « lang ».

Une fois cela fait, vous pouvez exécuter votre application et saisir dans le navigateur l’URL vers le fichier index.html : http://monapplication/swagger-ui/index.html. Ensuite, vous devez saisir dans la zone de texte du bandeau d’entête le lien vers le EndPoint JSON http://monapplication/swagger/v1/swagger.json, puis cliquer sur Explorer :

L’interface de Swagger a été mise en place de telle sorte que sa customisation soit assez simple. Vous avez à votre disposition plusieurs options pour effectuer cela.