Seguramente, durante el desarrollo de la API, las dificultades con la documentación aparecieron más de una vez: o no existe, entonces no muestra el comportamiento descrito en el código.
Desde el punto de vista del desarrollador, escribir documentación (solo interna) lleva no menos tiempo que escribir el código en sí. ¿Eso es familiar? Entonces bienvenido al gato.
¿Hay algún problema?
Nuestro equipo ha estado desarrollando la API durante mucho tiempo, que es la base de nuestro producto, pero en ese momento no había usuarios activos, por lo que nadie vio la necesidad de documentar algo para uso externo. Como todos los equipos, comenzamos con documentación interna: primero un método, luego otro. En nuestro espacio en Confluence, puede encontrar una docena de otras páginas que muestran información bastante repetitiva: qué tipo de método API, qué ruta de consulta tiene, qué parámetros y qué obtenemos en la salida.
Todo estaría bien, pero el código cambia y crece constantemente, las necesidades comerciales están cambiando. Junto con los cambios de código, las API pueden cambiar, lo que inevitablemente conduce a cambios en estas páginas. Bueno, si es una página y solo 1 vez. ¿Y si hay más cambios?
Se nos ocurrió una solución (nuestra propia bicicleta), tanto como sea posible, mientras realizamos las actividades habituales del desarrollador, para no pensar en escribir y actualizar la documentación interna.
Algunas soluciones
Hay diferentes opciones sobre cómo se pueden interconectar el código y su especificación, pero por mi parte, distingo dos:
- Código primero, especificación siguiente
- Especificación primero, código siguiente
Comenzaré con el segundo, como con la opción que menos nos convenía.
La especificación primero, el código siguiente trata sobre la generación de código, basado en la especificación, es decir, el código no existe hasta que se escribe la especificación.
El ejemplo más simple es Swagger Codegen.
Nuestra empresa cuenta con equipos que utilizan este enfoque en su producto, pero en nuestro caso no era muy adecuado. En el momento en que nos enfrentamos a una necesidad, ya habíamos escrito muchos métodos API, por lo que, por el bien de la documentación, no queríamos cambiar radicalmente los procesos de desarrollo: primero escribimos borradores, luego codificamos y solo luego la descripción de la especificación.
Primero el código, luego la especificación: todo es simple, primero escribimos el código y luego la especificación. Pero entonces surgió la pregunta, ¿y si no queremos hacer movimientos innecesarios para que se genere la especificación?
Varias aplicaciones en nuestra empresa utilizan este enfoque, pero no está particularmente automatizado: los métodos API están ponderados con todo tipo de anotaciones, en función de las cuales se generó la especificación. Pero estas mismas anotaciones a menudo no corresponden a la realidad, porque las necesidades y capacidades de la aplicación están creciendo y cambiando.
"Eres un programador", me dije, y decidí escribir un pequeño prototipo que me permitiera no escribir toda esta basura rutinaria.
Al realizar la siguiente tarea y escribir la enésima prueba funcional, me di cuenta de que ya tenemos toda la información para la especificación.
Tenemos pruebas funcionales que contienen casi toda la información que necesitamos:
- Como se llama
- Lo que se llama (parámetros, cuerpo, encabezados, etc.)
- Qué resultado se espera (código de estado, cuerpo de respuesta)
¿Por qué no hacer tu propia bicicleta?
Casi todo lo que usualmente escribimos en las especificaciones que tenemos. El caso para pequeño - codifique este caso.
Como nuestra aplicación está en PHP, la reflexión vino en mi ayuda. Usando un poco de magia de reflexión, recopilamos todos los métodos API disponibles para nosotros, tomamos datos de pruebas funcionales, extraemos datos sobre la autorización y su tipo. Desde las anotaciones habituales hasta los métodos, obtenemos la descripción del método en sí. Después de mezclar todo esto, sazonar con características específicas para el marco utilizado en nuestras soluciones, en un par de semanas obtenemos una solución que prácticamente no requiere tiempo adicional del desarrollador.
Generar una especificación es solo el primer paso: debe obtener documentación de la especificación que pueda proporcionar un desarrollador externo. Uno de los requisitos para la documentación es que debe presentarse en varios idiomas, pero por el momento, solo generamos documentación en inglés. Hasta ahora, suficiente, pero será necesario conectar un mecanismo para recibir transferencias a nuestro esquema de generación de especificaciones.
El problema que originalmente resolvimos. Pero con esta solución hay muchos riesgos:
- Precio apoya tu propia bicicleta
- Extensión de la funcionalidad necesaria.
- Actualización y sincronización de traducciones.
Deben tenerse en cuenta estos riesgos y, si comienzan a funcionar, actúen.