Integrando la documentación técnica de las APIs en el ciclo de vida del desarrollo de software

Abstract

Las APIs son ventajosas al facilitar la transición de aplicaciones monolíticas a microservicios en la nube, en respuesta a la necesidad de agilidad y generación de valor. En la "economía de APIs", las empresas son consumidores y productores de APIs, que actúan como componentes esenciales simplificando el desarrollo de productos y servicios. Este enfoque brinda flexibilidad, eficiencia y una ventaja competitiva en el mercado actual. En ese proceso la documentación técnica desempeña un papel fundamental en el éxito de las empresas, ya que constituye el primer punto de contacto con los desarrolladores. La retroalimentación constante de los consumidores y la mejora continua de la documentación aumentan significativamente las probabilidades de éxito de las empresas, por lo que debe ser dinámica y adaptarse a las exigencias de un mercado demandante. Para lograrlo, es esencial integrarla en el ciclo de vida del desarrollo de software. En este estudio, se investigan y establecen pautas necesarias para que las empresas puedan publicar una documentación sólida, basada en una estructura moderna e integrada en el proceso de desarrollo. Se utilizan técnicas como la evaluación comparativa para recomendar herramientas tecnológicas apropiadas según el escenario y los requisitos de la empresa. Se consideran factores como el tiempo, los recursos disponibles y la calidad esperada para establecer un conjunto de criterios que posteriormente se evalúan en una muestra. Los resultados obtenidos destacan la importancia de identificar la tipología y responsabilidad de cada documento, ya que establecer estas responsabilidades garantiza la solidez de los resultados. Se establece una forma y narrativa efectiva para presentar los beneficios del producto tecnológico. Además, se concluye que la generación automática de la especificación del API es un componente clave para alcanzar los objetivos planteados en este trabajo. Por último, se establece que la calidad del producto en sí mismo no es suficiente para garantizar el éxito; factores como una mala documentación pueden perjudicar directamente el desempeño de la empresa.

APIs have multiple advantages, and one of the most prominent is their ability to facilitate the transition from monolithic applications to cloud-based microservices. This transition has emerged as a response to the growing need for agility and value generation. As a result, the concept of ‘API economy’ has emerged, where companies play two fundamental roles: consumers and producers of APIs. In this new approach, APIs act as essential building blocks or components that simplify the process of developing and building products and services. This paradigm enables greater flexibility and efficiency in the development of technological solutions, providing companies with a competitive advantage in the current market. Crucially, within this landscape, meticulous technical documentation assumes a pivotal role in determining the success of companies, serving as the initial touchpoint for developers. The continuous feedback loop between consumers and the relentless enhancement of documentation substantially augment the probability of success for enterprises. Thus, it becomes imperative for documentation to possess a dynamic and adaptable nature, ensuring alignment with the demands of an exacting market. Integration into the software development lifecycle stands as an indispensable prerequisite. The present study delves into the comprehensive investigation and establishment of vital guidelines that enable companies to publish robust documentation, firmly rooted in a contemporary and seamlessly integrated structure within the development process. Leveraging techniques such as comparative evaluation, appropriate technological tools are recommended, tailored to specific company scenarios and requirements. Multiple factors, encompassing time, resource availability, and expected quality, are conscientiously considered establishing a set of criteria that is subsequently evaluated across a representative sample. The findings distinctly underscore the paramount importance of identifying the typology and responsibility of each document, as meticulous delineation of these responsibilities guarantees the solidity of outcomes. Moreover, a compelling form and narrative are thoughtfully constructed to effectively communicate the benefits of the technological product. Furthermore, a key conclusion derived from this research asserts that the automated generation of API specifications, exemplified by OpenAPI, constitutes a pivotal element in successfully attaining the objectives. It is firmly established that product quality alone does not suffice to ensure triumph; rather, factors such as subpar documentation directly impede a company’s performance.