Resuelve los problemas a los que otros ya nos hemos enfrentado en desarrollo .net
Hasta ahora puedes encontrar diferentes cosas en este blog para una configuración básica de swagger como herramienta para documentar tus APIs.
Con esta entrada vas a darle algo mas de riqueza a la documentación sobre tus servicios. Con aspectos como “Implementation Notes” o el tipo devuelto por la respuesta en caso de tener 200 o diferentes códigos de error.
Vengo utilizando swagger para documentar mis desarrollo con API desde que lo descubrí, y ahora que estoy empezando a utilizar .Net Core para mis desarrollos, no podía dejar de utilizarlo.
En esta entrada te voy a explicar como instalar y configurar swagger íntegramente desde el startup de tu servicio de .Net Core.
Continúo la serie de entradas sobre swagger como herramienta para documentar tus APIs.
En anteriores entradas he escrito sobre cómo configurarlo para una documentación básica de un endpoint, con lo que apenas conseguirás darle una funcionalidad básica y disponer del tipo de verbo Http y parámetros recibidos o respuestas devueltas. También he escrito sobre cómo utilizarlo con autenticación basada en bearer token, OAuth, lo cual es vital para probar desde swagger una API con este mecanismo de seguridad.
Ahora voy a explicarte como añadir documentación sobre la funcionalidad que tu endpoint expone, permitiéndote reflejar en una frase su comportamiento.
Para usar servicios de tu WebApi autenticados swagger usa por defecto un input para usar un Api key. Pero lo mas probable es que en tu proyecto WebApi estés utilizando autenticación mediante usuario y contraseña para obtener un jwt token, para posteriormente utilizar el token con un header Authorization bearer token.
Si quieres saber como configurar esta característica para usar bearer token desde swagger para poder consumir endpoints con este token, estás en la entrada que necesitas.
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.
Si estas buscando la forma de documentar tu API, swagger es lo que buscas, es justamente eso.
Swagger es un framework para documentar APIs Rest desde muy diferentes fuentes: Archivos de configuración, XML, C#, Javascript, Ruby, PHP, Java, Scala… además existen multitud de módulos que te pueden ayudar a integrarlo en tu proyecto.