Wiki

Has cargado una revisión vieja del documento! Si la guardas crearás una versión nueva con estos datos.

====== Buenas prácticas de desarrollo de software: Documentación ======
Esta sección está dedicada al proceso de documentación de artefactos de software especialmente Servicios Web.

===== Tipos de Documentación =====

* **Pública**: Documentación que esta disponible publicamente, es decir puede ser accedida directamente por cualquiera Como: Manuales públicos, Páginas Web o especificaciones de APIs Rest como Swagger u OpenAPI.
  * **Privada**: Aquella que se utiliza internamente dentro la empresa que desarrolla el producto de software como: Documentos de arquitectura, Javadoc, Fichas técnicas de integraciones.

==== Consideraciones ====
En esta sección nos centraremos en las especificaciones APIs Rest las cuales son las que más se utilizan en las tecnologías actuales.

===== Documentación de APIs Rest: OpenAPI =====

==== ¿Que es OpenAPI? ====

OpenAPI es el estándar global para escribir APIs RESTful. Es como una especificación que permite a los desarrolladores de todo el planeta estandarizar el diseño de sus APIs.

Además, cumple con toda la seguridad, el versionado, el manejo de errores y otras mejores prácticas al escribir APIs REST desde cero. Y no sólo desde el principio, sino que incluso las APIs existentes pueden ajustarse para cumplir con un estándar global((https://codigoencasa.com/openapi/)).

La especificación OpenAPI es un lenguaje de especificación para API HTTP que proporciona un medio estandarizado para definir su API ante otros. Podemos descubrir rápidamente cómo funciona una API, configurar la infraestructura, generar código de cliente y crear casos de prueba. [[https://www.openapis.org/|Para mas información -> Ir al sitio web oficial.]]

===== Modelo Propuesto Fabrica de Software =====
A continuación se comparte el proceso de documentación propuesto para la documentación de Servicios Web. Favor tener presente que este proceso dependerá de la versión java y el framework utilizado.

===== Dependencias =====

<code xml>

<parent>
	<groupId>org.springframework.boot</groupId>
	<artifactId>spring-boot-starter-parent</artifactId>
	<version>2.7.17</version>
	<relativePath/> 
</parent>

<properties>
	<java.version>11</java.version>
</properties>		

<dependency>
    	<groupId>org.springdoc</groupId>
    	<artifactId>springdoc-openapi-ui</artifactId>
    	<version>1.6.12</version>
</dependency>
</code>

===== Notas =====
  * Toda actualización debe estar soportada por un ticket o control de cambios.
  * Toda actualización debe estar validada exitosamente por el rol de QA.
  * El versionamiento aplica para la liberación de release. 
  * Cada versión debe ser almacenada en su repositorio especifico.

[[ada:howto:sicoferp:factory:goodsoftwaredevelopmentpractices|←Volver atras]]

Resumen de la edición

Wiki

Herramientas de usuario

Herramientas del sitio

Herramientas de la página