Parece que tiene dos problemas aquí: un problema de lectura (“¿Cómo pueden los desarrolladores buscar fácilmente el formato de una solicitud dada?”) Y un problema de escritura (“¿Cómo puedo asegurarme de que la documentación siempre refleje la realidad?”)
Actualmente, por lo que parece, está haciendo su análisis JSON y la composición de resultados ad-hoc en su código de aplicación. Además, supongo que está haciendo lo mismo ad-hoc en la dirección opuesta en su código del lado del cliente. Y también está actualizando manualmente su documentación. Eso significa que actualmente tiene tres fuentes de verdad, que generalmente es una receta para la inconsistencia.
Una buena respuesta aquí es la metaprogramación. En este contexto, eso significa que especifica su API JSON en un solo lugar y escribe código que genera bibliotecas del lado del cliente para componer solicitudes y decodificar respuestas, bibliotecas del lado del servidor para decodificar solicitudes y componer respuestas, y (posiblemente) documentación, que puedes usar una bonita interfaz de usuario web si quieres. Digo “posiblemente” en el caso de la documentación porque un enfoque es usar la documentación como entrada para su herramienta de generación de código, lo que significa que las personas pueden referirse directamente a eso según sea necesario y estar 100% seguros de que es preciso.
- ¿Qué les impresiona a los empleadores al mirar la cartera / github de un desarrollador web?
- ¿Cuáles son los pros y los contras de la tenencia múltiple en una aplicación Rails?
- Cómo guardar un documento CSS y hacer referencia a él en un documento HTML (es decir, definir una clase en CSS e identificar un elemento como esa clase en HTML)
- ¿Cómo pueden las pequeñas agencias de diseño web y los autónomos competir con servicios baratos como Wix?
- Cómo crear y administrar una base de datos para la sección de comentarios en mi sitio web usando phpMyAdmin
En términos prácticos, esto significa que el código de aplicación que mantiene a mano nunca se ocupará directamente de las solicitudes o respuestas JSON; en su lugar, tratará con estructuras de datos que son consumidas o producidas por funciones de biblioteca generadas, y esas funciones de biblioteca asignarán las estructuras de datos a las representaciones JSON apropiadas.
Un beneficio adicional de este enfoque es que, una vez que lo haga funcionar, es probable que produzca código con menos errores que sea más fácil de probar, en virtud de darle un solo lugar para aplicar correcciones a nivel mundial o para insertar globalmente datos ficticios o verificadores de sanidad de respuesta .
En cuanto al problema de lectura, un enfoque a considerar, si todos sus desarrolladores están acostumbrados a trabajar en una línea de comando UNIXish, es hacer que su generador de código escupe páginas de manual. Luego, un desarrollador puede usar el comando “man” para ver la documentación de la API para un punto final en particular. Pero probablemente también sea adecuado simplemente poner las especificaciones de cada punto final en un archivo separado con el mismo nombre que el punto final.
TL; DR: Genere su código a partir de su documentación, no al revés.
