Cómo personalizar la información que muestra Swagger
En esta entrada, vamos a ver algunas pautas generales a la hora de personalizar la presentación de Swagger. Por defecto, Swagger nos muestra la información de nuestras APIs en un formato genérico, pero si nuestra API va a tener un carácter comercial o queremos darle un formato un poco más personalizado, ¿cómo lo podemos hacer?.
Aquí voy a explicar de forma muy breve y sencilla, una de esas formas de hacerlo.
Manos a la obra…
Lo primero que haremos será descargamos el paquete de swagger-ui de GitHub para descomprimirlo en nuestro ordenador y quedarnos con la carpeta dist y sus elementos.
Esta carpeta tiene diferentes elementos (js, css, png y html fundamentalmente).
Por otro lado y para nuestro proyecto ASP.NET Core, instalaremos el paquete de NuGet Microsoft.AspNetCore.StaticFiles. El objetivo de este paquete es el de servir información estática en nuestro proyecto (un poco más adelante veremos donde poner esa información estática).
Una vez completados todos estos pasos, iremos al fichero Startup.cs de nuestro proyecto y escribiremos lo siguiente:
public void Configure(IApplicationBuilder app, IHostingEnvironment env) { app.UseStaticFiles(); //...
Como ya tendremos Swagger instalado, si queremos (en principio sería lo suyo), también podemos comentar el siguiente código (no es estrictamente necesario, pero evitaremos mostrar la documentación por defecto de Swagger mostrando sólo la que queremos personalizar y no las dos):
app.UseSwaggerUI(c => { c.SwaggerEndpoint(SwaggerConfiguration.EndpointUrl, SwaggerConfiguration.EndpointDescription); });
Un vez realizados todos estos pasos, vamos a crear una carpeta en el proyecto de nombre wwwroot.
Dentro de esta carpeta, metemos la carpeta dist que comentábamos al principio de esta entrada.
Abre el fichero index.html y cambia la dirección del fichero json de la información de swagger (lo encontrarás en la línea 77 del fichero aproximadamente). En mi caso, he cambiado el valor que aparece por defecto por:
url: «http://localhost:1392/swagger/v1/swagger.json»,
Una vez completado todo esto, si ejecutamos nuestro proyecto y nos vamos a:
http://[server]/swagger
El visualizador de la ayuda no funcionará ya que hemos comentado el código que hace esto.
Si ejecutamos nuestra Web API y nos vamos a:
http://[server]/dist/index.html
Veremos algo parecido a lo siguiente:
Evidentemente, no hemos personalizado nada de la carpeta dist, pero es aquí a partir de donde podremos trabajar.
Ahora bien, existe un repositorio de Swagger donde encontrar prácticamente esto mismo pero más ordenado y extendido. Se trata de una carpeta dist diferente.
El mecanismo es el mismo, descargar un repo de GitHub, descomprimirlo, copiar y pegar la carpeta dist en wwwroot y cambiar en index.html la Url a nuestro json. Una vez hecho esto, ejecutaremos nuestra API y la ayuda aparecerá con el formato que nosotros personalicemos. Encontrarás este repo en este enlace.
¡Happy Coding!