Documentar una API REST en Spring Boot con OpenAPI convierte tu proyecto en algo profesional, fácil de consumir y listo para integrarse con otros sistemas. Aquí aprendes a integrar Springdoc OpenAPI, generar la documentación automáticamente y personalizarla con anotaciones útiles para equipos de desarrollo backend.

¿Por qué documentar una API REST con OpenAPI?

Una API que funciona bien no basta. Quien la consume necesita saber qué endpoints existen, qué datos espera cada uno y qué respuestas puede recibir. Ahí entra OpenAPI, un estándar que describe tu API de forma legible para humanos y máquinas.

Con Springdoc obtienes esa documentación casi sin esfuerzo. Solo agregas la dependencia y la librería escanea tus controladores para construir una interfaz interactiva donde se pueden probar los endpoints en vivo.

¿Qué es Springdoc OpenAPI? Es la librería oficial que integra OpenAPI con aplicaciones Spring Boot y genera documentación automática a partir de tus controladores y anotaciones.

¿Cómo integrar Springdoc OpenAPI en un proyecto Spring Boot?

La integración parte de la página oficial springdoc.org, en la sección Getting Started, donde encuentras la versión recomendada de la dependencia.

El flujo es directo:

1. Copia la dependencia desde la documentación oficial.
2. Pégala en el archivo build.gradle, separando grupo, artefacto y versión con dos puntos si vienes desde el formato Maven.
3. Sincroniza Gradle para que descargue la librería.
4. Lanza la aplicación.

Una vez arriba el servidor, accedes a la documentación en una ruta como localhost:8090/platzi-play/api/swagger-ui.html [04:12]. Ahí aparece Swagger UI, la interfaz visual que lista todos los métodos del controlador, su estructura de respuesta y un botón para ejecutar peticiones reales.

¿Qué muestra Swagger UI automáticamente?

Sin tocar más código, Swagger UI ya expone:

• Todos los endpoints GET, POST, PUT y DELETE de tus controladores.
• La estructura del cuerpo de respuesta esperada.
• Un formulario para probar cada endpoint con su URL y resultado.
• Las validaciones declaradas con anotaciones, como obligatoriedad del título o el rango del rating entre 0 y 5 [05:48].

Eso último es clave: si en tu DTO marcaste un campo como obligatorio o con un tamaño mínimo, la documentación lo refleja en el esquema. Comunicas exactamente qué esperas recibir.

¿Cómo personalizar la documentación con anotaciones de Swagger?

La documentación generada es funcional, pero los nombres por defecto como movie-controller no comunican bien. Por eso Swagger v3 incluye anotaciones para personalizar títulos, descripciones, parámetros y respuestas.

¿Cómo cambiar el nombre de un controlador con la anotación Tag?

Dentro del controlador, debajo del @RequestMapping, agregas la anotación @Tag desde io.swagger.v3.oas.annotations.tags [07:25]. Le pasas dos atributos:

• name: el nombre visible, por ejemplo movies.
• description: una frase corta como operaciones acerca de las películas Platzi Play.

Al reiniciar, el nombre genérico desaparece y queda tu texto personalizado, en el idioma que prefieras.

¿Cómo describir un endpoint con Operation y ApiResponse?

Para un método como obtener una película por su ID, usas la anotación @Operation con dos atributos principales:

• summary: un título corto, por ejemplo Obtener una película por su identificador.
• description: una explicación más larga, como Retorna la película que coincida con el identificador enviado.

Dentro de @Operation también declaras las posibles respuestas con @ApiResponse [09:30]. Cada una recibe un responseCode y una description:

• 200: Película encontrada.
• 404: Película no encontrada.

¿Qué hace la anotación ApiResponse? Documenta cada código HTTP que tu endpoint puede retornar y la descripción que verá quien consuma la API en Swagger UI.

¿Cómo evitar que un 404 muestre cuerpo de respuesta?

Por defecto, Swagger asume que toda respuesta tiene cuerpo. Cuando un 404 no debería retornar contenido, agregas el atributo content = @Content vacío dentro del @ApiResponse [11:05]. Así la documentación deja claro que esa respuesta no incluye payload.

¿Cómo documentar parámetros con la anotación Parameter?

Los @PathVariable también merecen contexto. Sobre el parámetro del método aplicas @Parameter desde Swagger v3 OAS y le defines:

• description: una frase como Identificador de la película a recuperar.
• example: un valor de ejemplo, por ejemplo 9.

Ese ejemplo aparece precargado en Swagger UI cuando alguien hace clic en Try it out. Si el ID existe, devuelve 200 con la película. Si pruebas con un valor inexistente como 900, retorna 404 correctamente [12:48].

¿Qué ventajas tiene mantener la documentación dentro del código?

Este enfoque, conocido como documentation as code, mantiene la descripción de la API junto a su implementación. Cada vez que evoluciona el proyecto, la documentación se actualiza sola.

Los beneficios concretos son:

• Pruebas inmediatas desde el navegador sin herramientas externas.
• Comunicación clara entre equipos de backend, frontend y QA.
• Integraciones más rápidas con otros sistemas que consumen la API.
• Menos discrepancias entre lo que el código hace y lo que la documentación dice.

Con esto tu API queda documentada de forma viva. ¿Qué endpoint vas a documentar primero en tu proyecto? Cuéntame en los comentarios.