Documentar servicios con swagger: implementation notes y response class

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.

Leer más…

Crea una API básica desde un proyecto vacío

Cuando creas un nuevo proyecto, ya sea de tipo WebApi o MVC, seguramente suelas utilizar plantillas. En muchos casos incorporan capacidad por encima de las necesarias, o condicionan tu desarrollo. No obstante es un muy buen punto de partida que se puede ajustar a tus necesidades. Suelen incluir unos controladores básicos, algunas vistas, les puedes incluir un mecanismo de autenticación y en ese caso te incluirán incluso modelo.

Sin embargo con las nuevas arquitecturas basadas en microservicios, es posible que no necesites nada de todo esto, y con unos simples servicios expuestos te sea más que suficiente para consumir la Api de un mircoservicio desde una aplicación SPA. Si este es el caso, en esta entrada te voy a mostrar como crear un proyecto de Api nuevo, sin utilizar ningún template, y haciendo uso de la clase StartUp en lugar de global.asax, como ya hacen muchos template, especialmente basados en .Net Core.

Leer más…

Cómo instalar y configurar swagger en .Net Core usando OAuth2

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.

Leer más…

Cómo documentar un servicio con swagger y summary.

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. 

Leer más…

Cómo habilitar autenticación OAuth en swagger

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.

Leer más…

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.

Leer más…