Cómo instalar swagger en tu WebApi

Los proyectos crecen, los endpoints se multiplican, las funcionalidades se extienden, y el legacy code llega con el tiempo.

Documentar adecuadamente tu WebApi es crucial para no acabar con un montón de servicios que con el tiempo se terminen convirtiendo en cajas negras. Si llega este momento, incluso a veces te planteas si escribir un nuevo endpoint en lugar de editar uno existente que ni recuerdas qué hacía.

Configura Swagger y comienza a disfrutar del placer de probar tu Api en cuanto expones el servicio, así como disfrutaras de autodocumentar sus propiedades.

Antes de empezar con la práctica, si te estas preguntando qué es swagger, puedes leer sobre ello en esta otra entrada.

Configurar las opciones básicas de swagger es muy fácil y prácticamente inmediato, pero tras ello permite una gran cantidad de opciones de personalización de las que iré escribiendo en diferentes entradas. En mi entrada sobre qué es swagger que menciono unas lineas mas arriba, menciono algunos de los ejemplos de personalización que permite.

Swagger puede configurarse desde diferentes fuentes, en mis artículos me voy a centrar en su configuración desde C#, con su .dll.

Para comenzar tienes que tener un proyecto de webapi creado claro, aquel que quieres documentar, obvio. En él instala el siguiente paquete Nuget, “Swashbuckle“.

Una vez lo tengas instalado aparecerá en tu App_Start una clase “SwaggerConfig.cs”, en este clase tendrás disponible la configuración básica de swagger, y una lista completa de sus funciones, las cuales están comentadas.

Puedes incluir la llamada a su Register en tu StartUp.cs o tu global.asax (según qué estés utilizando). O por el contrario puedes usar esta clase solo como fuente de documentación y usar directamente sus funciones en tu Startup.

Esta es la configuración básica de swagger si añades sus funciones directamente al HttpConfiguration() de tu startup.

Solo con esta configuración swagger será capaz de mostrar tus controladores, con los servicios expuestos por cada uno de ellos, con su verbo Http correspondiente y sus parámetros de entrada y salida.Sobre las opciones adicionales que es posible mostrar y configurar hablaré en otras entradas en el futuro.

Con estas acciones básicas su aspecto será algo parecido a esto, según cuales sean tus endpoints claro está.

Cada uno los endpoints que puedes ver es un elemento collapse, que puede expandirse para realizar una llamada. Además puedes ver 2 controladores (Account y Values).

Pues listo, si arrancas tu proyecto y accedes a la url “/swagger”, verás la documentación de tu API.

Una de las primeras dudas que seguro que se te planteará, será como puedes usar endpoints que requieran autenticación mediante bearer token, usando oauth. Pues aquí aparece un api_key donde insertar el token no incluye este Authentication header con el “bearer token”. Tengo una buena noticia, la interfaz de swagger es completamente personalizable mediante html/javascript/css, y otra aún mejor, te cuento como hacerlo en esta entrada sobre habilitar autenticación OAuth en swagger.

Espero que esta entrada te sea de utilidad, y que si usas otros mecanismos para documentar tus API, o hay algo concreto que quieras preguntar o comentar sobre swagger, te sientas libre de contarlo a través de un comentario.

 

Deja un comentario