¶ 1. Visión General.
Swagger es una herramienta que facilita la creación, documentación y consumo de APIs (Application Programming Interface). Proporciona una interfaz interactiva que permite a los desarrolladores y consumidores externos visualizar, probar e interactuar con los endpoints de una API de manera intuitiva. A través de Swagger, es posible generar automáticamente la documentación de la API a partir del código fuente, asegurando que la documentación esté siempre actualizada y sincronizada con las implementaciones. Además, Swagger admite una amplia gama de lenguajes de programación y frameworks.
¶ 2. Autenticación y Autorización.
Swagger es accesible de forma predeterminada solo en el entorno de desarrollo. Para entornos de producción, la habilitación es opcional mediante configuración.
Comportamiento
| Entorno | Parámetro SwaggerEnabled | Usuario Autenticado | Resultado |
|---|---|---|---|
| Desarrollo | N/A | Sí | ✓ Acceso concedido |
| Desarrollo | N/A | No | 401 Unauthorized |
| Producción | false (predeterminado) | Sí/No | 403 Forbidden |
| Producción | true | Sí | ✓ Acceso concedido |
| Producción | true | No | 401 Unauthorized |
- Devuelve 403 (Forbidden) cuando Swagger está deshabilitado para el entorno.
- Devuelve 401 (Unauthorized) cuando el usuario no está autenticado.
Cómo habilitar en producción
Incluya la configuración en el archivo appsettings.json:
{
"SwaggerEnabled": true
}
- En entornos de producción, el valor predeterminado es false.
Tenemos algunas formas de autenticación dentro de Swagger; las más utilizadas normalmente son:
- Basic: Autorización utilizando usuario y contraseña, separados por ":" convertidos en Base64;
- Bearer: Es un Schema que utiliza un Token del tipo JWT (JSON Web Token) que autoriza al usuario a acceder a las APIs;
- OAuth 2: Es un protocolo de autorización mediante Token;
¶ 3. Uso.
Para abrir Swagger, usaremos el endpoint: URL.../swagger/index.html
- Ejemplo de endpoint en un entorno cloud:
qablue.tech6cloud.com/swagger/index.html; (en este caso, qablue es el nombre de su dominio.) - Ejemplo de endpoint en un entorno local:
(servidor del IIS)/(nombre de la aplicación en IIS)/swagger/index.html
La URL informada antes de la API dependerá de su dominio en la cloud o, en caso de entorno local, de las configuraciones informadas en su IIS (Internet Information Services).
Al acceder al endpoint se abrirá una página que contiene todas las APIs del sistema. Haga clic en 
para expandir la API seleccionada.
- Se mostrarán los parámetros necesarios para la ejecución de la API y también las posibles respuestas que el sistema puede devolver, además de una visualización detallada de la solicitud. Para habilitar la inserción de parámetros y ejecutar la API, haga clic en "Try it out"
- Al hacer clic en "Try it out" se habilitará la inserción de datos en los parámetros, además de mostrar el botón "Execute", que ejecutará la API según los parámetros ingresados
- Al ejecutar la API, Swagger devolverá una respuesta con el código y la descripción, informando sobre el éxito o el fallo de la ejecución. En caso de fallo, devolverá detalladamente el código de error y el motivo del fallo
Para obtener más información y formas de consumir las APIs, visite nuestro centro de ayuda: Integración de Datos
¶ 4. Q&A
Preguntas Frecuentes
1. ¿Cómo acceder a Swagger en un entorno de producción?
Para acceder a Swagger en un entorno de producción, es necesario habilitar la configuración en el archivo appsettings.json, definiendo "SwaggerEnabled": true. Por defecto, Swagger está deshabilitado en producción por razones de seguridad.
2. ¿Por qué recibo el error 403 (Forbidden) al intentar acceder a Swagger?
El error 403 (Forbidden) indica que Swagger está deshabilitado para el entorno actual. En entornos de producción, Swagger debe habilitarse explícitamente mediante la configuración "SwaggerEnabled": true en el archivo appsettings.json.
3. ¿Por qué recibo el error 401 (Unauthorized) al acceder a Swagger?
El error 401 (Unauthorized) significa que no está autenticado en el sistema. Es necesario iniciar sesión en la aplicación antes de acceder a Swagger, independientemente del entorno (desarrollo o producción).
4. ¿Cuáles son los métodos de autenticación disponibles en Swagger?
Swagger admite tres métodos principales de autenticación:
- Basic: Utiliza usuario y contraseña separados por ":" y convertidos en Base64.
- Bearer: Utiliza un Token JWT (JSON Web Token) para autorización.
- OAuth 2: Protocolo de autorización mediante Token.
5. ¿Cómo ejecutar una API a través de Swagger?
Para ejecutar una API en Swagger:
- Haga clic en la API deseada para expandirla.
- Haga clic en el botón "Try it out".
- Complete los parámetros necesarios.
- Haga clic en el botón "Execute".
- Visualice la respuesta devuelta por el sistema.
6. ¿Cuál es la URL predeterminada para acceder a Swagger?
La URL predeterminada sigue el formato: URL.../swagger/index.html. En un entorno cloud, sería algo como sudominio.tech6cloud.com/swagger/index.html. En un entorno local, depende de la configuración del IIS: (servidor del IIS)/(nombre de la aplicación en IIS)/swagger/index.html.
7. ¿Qué significa la respuesta que Swagger devuelve después de ejecutar una API?
La respuesta de Swagger incluye un código de estado HTTP y una descripción. Los códigos 2xx indican éxito, mientras que los códigos 4xx o 5xx indican errores. En caso de fallo, Swagger proporciona detalles sobre el código de error y el motivo del fallo.
8. ¿La documentación de Swagger se actualiza automáticamente?
Sí, Swagger genera automáticamente la documentación de la API a partir del código fuente, asegurando que la documentación esté siempre actualizada y sincronizada con las implementaciones realizadas.
9. ¿Es seguro dejar Swagger habilitado en producción?
Swagger expone información sobre la estructura y endpoints de su API. Por razones de seguridad, está deshabilitado por defecto en producción. Habilítelo solo si hay una necesidad específica y asegúrese de que solo usuarios autenticados puedan acceder a él.
10. ¿Puedo probar todas las APIs del sistema a través de Swagger?
Sí, Swagger muestra todas las APIs disponibles en el sistema, permitiendo visualizar, probar e interactuar con cada endpoint de forma interactiva. Es una herramienta completa para que los desarrolladores y consumidores externos prueben las funcionalidades de la API.