Swagger UI es una gran herramienta para visualizar e interactuar con las especificaciones OpenAPI. A medida que trabajas con Swagger UI, notarás que las URL juegan un papel importante en la configuración y el acceso a la documentación de la API. En esta publicación, desmitificaremos las URL de Swagger UI para ayudarte a usarlas de manera más efectiva.
¿Qué es Swagger UI?
Swagger UI es una herramienta que permite al usuario interactuar con las API utilizando la documentación de la especificación OpenAPI. Lee el documento de especificación y lo muestra en un formato visualmente interactivo. Esto ayuda a los desarrolladores a comprender las API, enviar solicitudes de prueba, depurar y usar tus API REST.
La URL de Swagger UI corresponde al punto final donde sirves tu archivo JSON de especificación OpenAPI. Esto significa que debes proporcionar una dirección web que apunte a la ubicación de tu archivo JSON de OpenAPI. Swagger UI lee este archivo para crear una interfaz fácil de usar accesible a través de esa URL. La estructura exacta de la URL puede variar debido a las diferentes configuraciones del servidor.
Características de Swagger UI
Swagger UI es una potente herramienta que proporciona una variedad de funciones para probar, comprender y visualizar las API. Algunas características se mencionan a continuación:
Las características clave incluyen:
- Pruebas en vivo de las API directamente dentro de los documentos
- Controles intuitivos para los parámetros de solicitud
- Generación de fragmentos de código para llamadas API
- Soporte de Markdown para el formato
- Herramientas para la colaboración en equipo
- Visualización automática del modelo de datos
- Organización y búsqueda de puntos finales de API
Parámetros de la URL de Swagger UI
Swagger UI tiene varios parámetros en la URL para configurar su comportamiento y apariencia. Estos afectan la forma en que se muestra la documentación de la API utilizando Swagger UI. Algunos de los parámetros de URL de Swagger UI más utilizados son:
URL:
Esto especifica la URL del archivo de especificación OpenAPI que Swagger UI debe usar para generar la documentación de la API. El formato de la URL es el siguiente:
http://localhost:8080/swagger-ui/?url=/path/to/your/api-spec.json
ConfigUrl:
configUrl proporciona la URL de una configuración JSON que personaliza y altera el comportamiento de Swagger UI.
http://localhost:8080/swagger-ui/?configUrl=/path/to/your/config.json
deepLinking:
Permite el enlace profundo a operaciones o etiquetas individuales en la documentación de la API. Es beneficioso al compartir enlaces directos a partes específicas de la documentación.
http://localhost:8080/swagger-ui/?url=/path/to/your/api-spec.json&deepLinking=true
oauth2RedirectUrl:
Permite a los usuarios redirigirse a otra URL después de una autenticación exitosa cuando tu API requiere autenticación OAuth 2.0.
http://localhost:8080/swagger-ui/?url=/path/to/your/api-spec.json&oauth2RedirectUrl=https://your-app.example.com/oauth2-redirect
defaultModelsExpandDepth:
Ajusta la profundidad predeterminada de los modelos en la documentación.
http://localhost:8080/swagger-ui/?url=/path/to/your/api-spec.json&defaultModelsExpandDepth=2
Cómo encontrar la URL de Swagger UI
Algunas personas se confunden sobre dónde está la URL de Swagger UI. Se genera en función de la configuración de tu proyecto. Para encontrar la URL, sigue estos pasos:
- Asegúrate de que tu proyecto esté configurado para generar documentación de Swagger.
- Para acceder a Swagger UI, debes combinar la URL base de tu API con el punto final de la documentación de Swagger. Esto dará como resultado tu URL de Swagger UI.
Por ejemplo, si estás alojando tu API en http://localhost:3000 y tu punto final de swagger es /swagger-ui/, entonces tu URL de Swagger se convertirá en http://localhost:8080/swagger-ui/.
Si aún tienes problemas para encontrar tu URL de Swagger UI, puedes consultar la documentación del framework o biblioteca que estás utilizando para generar tus API. Esto ayudará a proporcionar información sobre cómo acceder a la URL para tu configuración específica.
¿Cómo cambiar la ruta predeterminada de Swagger UI?
La ruta predeterminada de tu Swagger UI depende de las configuraciones de tu servidor. Se construye en función de la ubicación y dónde has implementado Swagger UI. Las rutas de URL predeterminadas se pueden cambiar de acuerdo con los requisitos del usuario y la implementación. El parámetro URL en la URL debe apuntar a la ubicación del archivo de especificación OpenAPI.
Hay muchos métodos para cambiar la ruta predeterminada de la URL de Swagger UI.
Cambiar el archivo de configuración de Swagger (Apache y Nginx):
Si estás utilizando un servidor web, puedes cambiar las configuraciones de tu servidor para manejar las solicitudes en una URL específica.
Apache:
En el caso de Apache, puedes modificar tu archivo de configuración para crear una regla de reescritura para que las solicitudes puedan redirigirse a tu ruta de Swagger UI. Debes abrir tu archivo de configuración, a menudo llamado 'httpd.conf' o 'apache2.conf'. Agrega tu regla de reescritura para la ruta deseada en este archivo.
RewriteEngine On
RewriteRule ^/api-docs/(.*)$ /path/to/your/swagger-ui/$1 [L]
Puedes reiniciar tu servidor Apache para que los cambios se reflejen.
Nginx:
Si estás utilizando Nginx, debes actualizar la configuración de tu archivo de servidor para definir una ubicación para manejar tus solicitudes. En el bloque del servidor, agrega tu ubicación.
server {
listen 80;
server_name your-domain.com;
location /api-docs {
alias /path/to/your/swagger-ui;
index index.html;
}
}
Verifica si hay errores de sintaxis después de realizar los cambios y vuelve a cargar tu Nginx para que los cambios se reflejen.
Usar frameworks como Express.js:
Usando Express.js, puedes configurar tus rutas para manejar las solicitudes de Swagger UI.
Para servir Swagger UI, debes definir una ruta en tu archivo de servidor Express.js.
const express = require('express');
const app = express();
app.use('/custom-path', express.static('swagger-ui'));
app.listen(3000, () => {
console.log('Server is running on port 3000');
});
Esto te permitirá acceder a tu Swagger UI en tu 'custom-path'.
Aprovechar Springboot para cambiar la ruta predeterminada:
En una aplicación Spring Boot, puedes modificar los archivos 'application.properties' o 'application.yml'. Puedes agregar la siguiente propiedad para cambiar la ruta predeterminada de Swagger UI en tus archivos 'application.properties' o 'application.yml'.
springfox.documentation.swagger-ui.path=/custom-path
Puedes reemplazar '/custom-path' según la ruta deseada.
A continuación, debes configurar el bean para personalizar la ruta. Puedes extender 'WebMvcConfigurerAdapter' para lograr esto.
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ViewControllerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
@Configuration
public class SwaggerUIConfiguration implements WebMvcConfigurer {
@Override
public void addViewControllers(ViewControllerRegistry registry) {
registry.addRedirectViewController("/custom-path", "/swagger-ui.html");
}
}
Asegúrate de tener las dependencias necesarias en Swagger para lograr estos resultados.
Luego, debes configurar la clase principal de tu aplicación.
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
public class SwaggerConfiguration {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("your.package.name"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Your API Documentation")
.version("1.0")
.build();
}
}
Reemplaza "your.package.name" con el paquete base de tus controladores.
Inicialización de Swagger UI:
Puedes ajustar el parámetro 'url' para que refleje la ruta de URL deseada. Esto te permitirá cambiar la ruta predeterminada de Swagger UI. Al inicializar Swagger UI en JavaScript, puedes realizar los siguientes cambios.
const ui = SwaggerUIBundle({
url: "/custom-path/swagger.json",
});
Usar Swagger UI para probar API
Al igual que otras herramientas de prueba de API, como Apidog, Swagger UI proporciona una forma eficiente y fácil de usar para probar las API. Debes seguir ciertos pasos para depurar y probar tus API utilizando el sitio de Swagger. Haz clic en Live Demo y comienza a explorar Swagger UI. Verás que se abre una ventana como esta.
Puedes explorar múltiples métodos HTTP/HTTPS como POST, GET, PUT, etc.
Puedes hacer clic en cualquier método y explorar. Si haces clic en el método POST, verás una opción para cargar una imagen y actualizar los parámetros del método. Puedes presionar 'Execute' y tu solicitud se ejecutará.
Puedes ver la respuesta a la solicitud POST desplazándote hacia abajo.
De manera similar, puedes trabajar con otros métodos dados y ver qué hacen. Esto te dará una buena idea de cómo funciona Swagger UI.
Considera Apidog para una documentación de API más robusta más allá de las capacidades de Swagger UI. Apidog permite la gestión completa del ciclo de vida de la API, incluyendo el diseño, la simulación, las pruebas, el control de versiones, la colaboración y más.
Con características avanzadas como la integración de CI/CD y los flujos de trabajo en equipo, Apidog ofrece un conjunto de herramientas más completo para optimizar la entrega de API. Su plataforma integral escala el desarrollo de API y mejora la productividad.
Solución de problemas de Swagger UI Localhost
Si tienes problemas con la URL de Swagger UI en localhost, hay varios pasos de solución de problemas que puedes consultar para diagnosticar y resolver el problema.
- Asegúrate de que tu servidor API esté en funcionamiento. Swagger UI no puede obtener la documentación si tu servidor tiene problemas para ejecutarse.
- Verifica tus configuraciones de Swagger para ver si están configuradas correctamente.
- Usa la URL correcta de Swagger UI con los puntos finales correctos.
- Borra la caché de tu navegador. A veces, pueden ocurrir errores inesperados con los datos almacenados en caché.
- Reinicia tanto tu servidor API como tu navegador después de realizar cualquier cambio.
- Verifica el formato de URL que estás utilizando para acceder a Swagger UI.
Conclusión
En conclusión, Swagger UI está ganando popularidad rápidamente entre los desarrolladores debido a sus amplias técnicas de gestión de API. Proporciona documentación bien estructurada y una interfaz fácil de usar. Los usuarios también pueden visualizar modelos de datos mientras realizan pruebas de API en vivo, lo que la convierte en una buena opción para las pruebas y la depuración de API.
Si bien Swagger UI tiene sus ventajas, también hay varias limitaciones que el usuario puede ver al probar las API. Proporciona una colaboración limitada entre los desarrolladores y no admite la integración con otras herramientas de gestión de API.
