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.

En mi primera entrada sobre instalar swagger en tu webapi comento que es necesario instalar el nuget llamado Swashbuckle, como sucede con muchas de las librerías habituales que ahora queremos usar en Core, hay que instalar Swashbuckle.AspNetCore.

A diferencia de SwashBuckle para .Net Framework, en este caso no se instalará ninguna clase con configuraciones iniciales de ejemplo, es necesario establecer esta configuración manualmente en el startup.

Dentro del startup, puedes definir una serie de opciones en el método ConfigureServices y otras opciones que determinan explicitamente el uso de swagger o swaggerUI. A continuación muestro un ejemplo sobre configurar algunas propiedades básicas.

Esta configuración básica ya haría que swagger funcionase y pudieses interactuar contra endpoints no autenticados. La imagen sería parecida a la siguiente que ya presento en mi anterior entrada.

Aún no verías la documentación XML creada a partir de summary, en esta entrada comento como hacerlo con .Net Framework.

En .Net Core no es muy diferente. Con click derecho sobre el proyecto y accediendo a propiedades, tendrás una opción sobre compilación (build), y tendrás un check para indicar que deseas usar la documentación XML y en que ruta generarla, bin/….

En mi caso he añadido el nombre del documento XML que he indicado para generar la documentación en el archivo appsettings.json (los web.config de Core), y luego lo he añadido en la configuración de swagger para que sepa desde donde debe tomar está información, actualizando el código anterior de la siguiente manera.

Ahora los endpoints ya incluirán la documentación adicional. De forma que el nuevo aspecto de swagger podría ser algo así.

Aún no podrás usar endpoints que requieran autenticación.

En otra entrada de mi blog hablo de cómo permitir usar OAuth con grant-Type password desde swagger para .Net Framework.  En ese caso se trata de usar la propiedad InjectJavaScript, para añadir a UI un archivo script que modifique el index de swagger para hacer uso en cada petición de un token previamente obtenido. La forma de introducir el token en las peticiones era con una función javascript de swagger-ui llamada SwaggerClient.ApiKeyAuthorization.

En este caso, ya está implementada la posibilidad de crear toda esta configuración sin necesidad de hacer ningún injectJavaScript, para ello, deberás actualizar las opciones de la siguiente manera:

Con esta nueva opción, ahora el aspecto de swagger será similar a este:

Si usas este botón Authorize, verás un formulario en que el que obtener un token contra la url generadora de token que hayas indicado en la configuración, cuando tu token se haya recibido, tu interfaz de swagger se refrescará, de forma que a partir de ese momento tus peticiones incluirán en el header el valioso “Bearer token”.

Pues listo, a seguir utilizando swagger para documentar tus API de .Net Core con una configuración del mismo integramente desde tu startup con C#.

Un saludo.

Deja un comentario