Documentar una API en Go con Swagger se vuelve mucho más rápido cuando combinas el modo agent de GitHub Copilot con tu conocimiento del lenguaje. Este flujo te muestra cómo pasar de un código sin documentación a una interfaz interactiva donde tu equipo puede explorar cada método, sin escribir casi ninguna línea manualmente.

Por qué pasar del modo edit al modo agent en Copilot

La diferencia entre los dos modos cambia por completo tu rol como desarrollador.

En modo edit, Copilot se limita a sugerir cambios sobre el código que ya tienes abierto. En modo agent, en cambio, le das permiso para crear archivos, ejecutar comandos en la terminal y reaccionar a los errores que va encontrando. Dejas de ser el instrumentista que toca cada nota y te conviertes en el director de la orquesta.

Y aquí viene lo interesante: como Copilot es un LLM, cada ejecución puede tomar un camino distinto. En la preparación de este flujo, tres intentos fallaron antes de que el cuarto funcionara limpio [00:32]. Por eso conviene tener claro el resultado esperado antes de soltar el primer prompt.

¿Qué hace el modo agent de Copilot? Permite que Copilot cree archivos, ejecute comandos en tu terminal y corrija errores de forma autónoma dentro de tu workspace, no solo que sugiera código.

Qué pasos sigue Copilot Agent para integrar Swagger en Go

El flujo arranca con un prompt único y Copilot va encadenando acciones.

Lo primero que hace el agente es actualizar main.go añadiendo las descripciones encima de cada función o método. Estas anotaciones son las que después leerán las herramientas de Swagger para generar la documentación. Cuando los cambios se ven bien, presionas Keep para conservarlos [02:30].

Después, Copilot pide ejecutar comandos en la terminal para instalar dependencias. Si un comando falla, el propio agente detecta el error y propone una versión alternativa. Es literalmente tanteando hasta dar con el comando correcto [03:05].

Entre los pasos clave que ejecuta están:

• Crear el archivo go.mod, que funciona como el requirements.txt de Python para gestionar paquetes en Go.
• Instalar las dependencias necesarias para Swagger.
• Ejecutar swag init, la herramienta que genera los archivos swagger.json y docs.go con las especificaciones de la API.
• Lanzar go run main.go para levantar el servidor local.

Una vez levantado, copias la URL que aparece en la terminal y la pegas en el navegador para ver la interfaz de Swagger.

Cuándo necesitas intervenir manualmente aunque uses Copilot

La automatización tiene límites y aquí es donde tu experiencia marca la diferencia.

En este flujo, swag init no funcionó al primer intento porque la instalación de Go usaba una ruta distinta. Copilot ofreció ejecutar un comando para arreglarlo, pero la solución real era usar export PATH apuntando a la ubicación correcta del binario [04:45]. Sin saber cómo está configurado tu entorno, ese error te detiene.

Algo similar pasó con la interfaz de Swagger. Al abrir la URL aparecía el mensaje de que las operaciones no estaban definidas en la especificación. Aprovechando que el modo agent acepta imágenes, basta con tomar una captura de pantalla, pegarla desde el portapapeles en el chat de Copilot y describir el problema con un prompt corto como no veo mis operaciones en Swagger [06:00].

Copilot detectó entonces que había tabulaciones mal puestas en las anotaciones del código, las corrigió, y al volver a ejecutar swag init los archivos swagger.json y docs.go quedaron con todas las especificaciones.

¿Qué generan swagger.json y docs.go? Son los archivos que Swagger lee para construir la documentación interactiva de tu API. Contienen las rutas, parámetros y respuestas de cada endpoint en Go.

¿Puedo pasarle imágenes a Copilot Agent? Sí. Puedes adjuntar capturas desde el portapapeles para que el agente analice errores visuales en interfaces o navegadores y proponga correcciones en el código.

Qué habilidades reales necesitas para trabajar con Copilot Agent

No se trata de delegar todo a la herramienta y esperar magia.

Para que este flujo funcione, necesitas reconocer cuándo un comando falla por configuración del entorno y no por el código, entender cómo se estructuran los paquetes en Go con go.mod, saber leer las anotaciones de Swagger para validar que estén bien formateadas, y comunicar el problema con prompts claros, apoyándote en imágenes cuando el error es visual.

Gracias a agent casi no se escribe código manual, pero el criterio para corregir el rumbo sigue siendo tuyo. ¿Has probado integrar Swagger en tus proyectos de Go con Copilot? Cuéntame en los comentarios qué parte del flujo te dio más problemas.