Software Libre

Documentando APIs

  • admin 

DOCUMENTANDO APIs

Filón de herramientas que generan la documentación automáticamente en la web de las APIs generadas a partir de los ficheros OpenAPI.

Voy poniendo todas las que he encontrado, porque son unas cuantas y el resultado es cuestión de gustos.

La que veo más avanzada en cuestión de actualizaciones y contribuyentes es Redoc:

https://apis.guru/blog/redoc-release/

https://swagger.io/blog/redoc-openapi-powered-documentation/

https://github.com/Rebilly/ReDoc/

Pero no es la única existente, y hay otros proyectos que tampoco tienen mala pinta, como Spectacle:

https://github.com/sourcey/spectacle

O DapperDox (este está hecho en golang ;-)):

http://dapperdox.io/

https://github.com/DapperDox/dapperdox

Por cierto, el propio Swagger tiene su sistema de generación de documentación, pero por lo que se ve en los blogs todo el mundo coincide que el Swagger es más indicado para editar y validar los ficheros OpenAPI (es decir, es una herramienta más orientada para trabajar en la parte de definición de los APIs), que para generar la documentación, al menos no de la forma tan extensa en que lo hacen las herramientas anteriores:

http://idratherbewriting.com/learnapidoc/pubapis_swagger.html

https://github.com/swagger-api/swagger-ui

Por ultimo, os dejo un enlace de un blog donde hace un repaso a bastantes herramientas de documentación de APIs, no solo de OpenAPI. Lo he encontrado después de haber encontrado los proyectos anteriores, pero lo veo bastante completo por si queréis explorar otras herramientas:

https://pronovix.com/blog/free-and-open-source-api-documentation-tools

Por cierto, los de APIs.guru son expertos en la publicación y análisis de APIs (son los creadores de Redoc) en un sistema llamado GraphQL (aparte del OpenAPI) y tienen varios proyectos sorprendentes para sacarle el máximo partido a esta forma de trabajar con modelos de datos:

https://apis.guru/

http://graphql.org/

El GraphQL lo usan para sus aplicaciones móviles la gente de Facebook, por ejemplo. Uno de los proyectos sobre GraphQL que han desarrollado los de APIs.guru es un navegador de GraphQL:

https://github.com/APIs-guru/graphql-voyager

La demo que tienen sobre varios APIs (incluido el de GitHub) es impresionante. Merece la pena echarle un vistazo para darse cuenta del potencial que tiene (p.e. elegid el esquema de GitHub y uno de los nodos raíces):

https://apis.guru/graphql-voyager/

Herramienta de desarrollo Colaborativo de Software Phacility

  • admin 

Herramienta de desarrollo Colaborativo de Software Phacility

Herramienta como entorno integrado de desarrollo colaborativo de software:

https://www.phacility.com/phabricator/

Lo hizo un ingeniero mientras estaba trabajando para Facebook, y posteriormente dejó la compañía para meterse con ello en exclusiva:

https://es.wikipedia.org/wiki/Phabricator

Lo bueno que tiene es que se puede integrar con el resto de herramientas y repositorios, como Git, etc… similar al Gitlab, pero más completo.

Software Libre

  • admin 

Software Libre

El Software Libre es un asunto de libertad, no de precio . Para entender el concepto, se debe pensar en «libre» como en «libertad de expresión», no como en «cerveza gratis» [N. del T.: en inglés una misma palabra ( free ) significa tanto libre como gratis, lo que ha dado lugar a cierta confusión].

Como «free» [libre] se refiere a libertad y no a precio, no existe contradicción entre la venta de copias y el software libre. La palabra comercial NO es sinónimo de «no libre», asimismo «software libre» no significa «no comercial»

«Software Libre» se refiere a la libertad de los usuarios para ejecutar, copiar, distribuir, estudiar, cambiar y mejorar el software. De modo más preciso, se refiere a cuatro libertades de los usuarios del software:

  • La libertad de usar el programa, con cualquier propósito (libertad 0).
  • La libertad de estudiar cómo funciona el programa, y adaptarlo a tus necesidades (libertad 1). El acceso al código fuente es una condición previa para esto.
  • La libertad de distribuir copias, con lo que puedes ayudar a tu vecino (libertad 2).
  • La libertad de mejorar el programa y hacer públicas las mejoras a los demás, de modo que toda la comunidad se beneficie. (libertad 3). El acceso al código fuente es un requisito previo para esto.

Un programa es software libre si los usuarios tienen todas estas libertades. Así pues, se debería tener la libertad de distribuir copias, sea con o sin modificaciones, sea gratis o cobrando una cantidad por la distribución, a cualquiera y a cualquier lugar. El ser libre de hacer esto significa (entre otras cosas) que no tienes que pedir o pagar permisos.

También se debería tener la libertad de hacer modificaciones y utilizarlas de manera privada en tu trabajo u ocio, sin ni siquiera tener que anunciar que dichas modificaciones existen. Si se publican tus cambios, no tienes por qué avisar a nadie en particular, ni de ninguna manera en particular.

Para que las libertades de hacer modificaciones y de publicar versiones mejoradas tengan sentido, se debe tener acceso al código fuente del programa (libertades 1 y 3). Por lo tanto, la posibilidad de acceder al código fuente es una condición necesaria para el software libre.

Para que estas libertades sean reales, deben ser irrevocables mientras no hagas nada incorrecto; si el desarrollador del software tiene el poder de revocar la licencia aunque no le hayas dado motivos, el software no es libre.

Son aceptables, sin embargo, ciertos tipos de reglas sobre la manera de distribuir software libre, mientras no entren en conflicto con las libertades centrales.

Por ejemplo, copyleft [«izquierdo de copia»] (expresado muy simplemente) es la regla que implica que, cuando se redistribuya el programa, no se pueden agregar restricciones para denegar a otras personas las libertades centrales. Esta regla no entra en conflicto con las libertades centrales, sino que más bien las protege.

Así pues, quizás hayas pagado para obtener copias de software GNU, o tal vez las hayas obtenido sin ningún coste. Pero independientemente de cómo hayas conseguido tus copias, siempre tienes la libertad de copiar y modificar el software, e incluso de vender copias.

Es aceptable que haya reglas acerca de cómo empaquetar una versión modificada, siempre que no bloqueen a consecuencia de ello tu libertad de publicar versiones modificadas. Reglas como «Si haces disponible el programa de esta manera, debes hacerlo disponible también de esta otra» pueden ser igualmente aceptables, bajo la misma condición. (Observa que una regla así todavía te deja decidir si publicar o no el programa). También es aceptable que la licencia requiera que, si has distribuido una version modificada y el desarrollador anterior te pide una copia de ella, debas enviársela.

Logo Proyecto GNU

En el proyecto GNU, se utiliza » copyleft » para proteger de modo legal estas libertades para todos. Pero el software libre sin » copyleft » también existe.

El modo más simple de hacer un programa libre es ponerlo en el dominio público, o sea, sin copyright. Esto permitirá que la gente comparta el programa y sus mejoras, si así lo desean. Pero también permitiría a quien no quiera cooperar, convertir el programa en software privativo. Pueden hacer cambios y distribuir el resultado como un producto privativo. Las personas que reciban el programa en su forma modificada no poseen la libertad que el autor original les dio debido a que el intermediario se la ha retirado.

Copyleft significa que cualquiera que redistribuya el software, con o sin cambios, no podrá restringir a nadie la libertad de copiarlo, redistribuirlo o cambiarlo. Copyleft garantiza que el usuario mantenga su libertad.

Si te interesa saber si una licencia concreta es de software libre, mira la lista de licencias de la FSF.

Otro grupo ha comenzado a usar el término «open source» [código abierto] para designar algo parecido (pero no idéntico) a «free software» [Software Libre]. Preferimos el término «software libre» porque, una vez que sabes que se refiere a libertad y no a precio, llama a pensar en la libertad.

¿Qué es entonces copyleft?

Copyleft es un concepto general. En el Proyecto GNU, las cláusulas específicas de distribución que emplean están contenidas en la Licencia Pública General de GNU, la Licencia Pública General Reducida de GNU y la Licencia de Documentación Libre de GNU.

El copyleft usa la ley de copyright, pero la da vuelta para servir a lo opuesto de su propósito usual: en lugar de ser un medio de privatizar el software, se transforma en un medio de mantener libre al software.

La idea central del copyleft es que le damos a cualquiera el permiso para correr el programa, copiar el programa, modificar el programa y redistribuir versiones modificadas–pero no le damos permiso para agregar restricciones propias.

De esta manera, las libertades cruciales que definen al «software libre» quedan garantizadas para cualquiera que tenga una copia; se transforman en derechos inalienables.

Para que el copyleft sea efectivo, las versiones modificadas deben ser también libres. Esto asegura que todo trabajo basado en el nuestro quedará disponible para nuestra comunidad si se publica. Cuando los programadores que tienen trabajo como programadores se ofrecen como voluntarios para mejorar un software GNU, es el copyleft lo que impide que sus empleadores digan: «no puede compartir esos cambios, porque los queremos usar para hacer nuestra versión propietaria del programa».

El requerimiento de que los cambios deben ser libres es esencial si queremos asegurar la libertad para cada usuario del programa.

¿Cuándo comenzó a utilizarse el término software libre?

Richard StallmanEn 1984 Richard Stallman comenzó a trabajar en el proyecto GNU (proyecto para hacer un si stema operativo totalmente libre originado en una necesidad de compartir software sin restricciones) y un año más tarde fundó la Free Software Foundation (FSF). Stallman introdujo una definición para free software y el concepto de «copyleft», el cual desarrolló para dar a los usuarios libertad y para restringir las posibilidades de apropiación del software.

GNU no es ni una licencia, ni una asociación ni una empresa, es sólo un proyecto.

Si quieres leer su historia, la encontrarás en:http://www.gnu.org/gnu/thegnuproject.es.html

¿Cómo se llama la licencia que indica que el software es libre?

La implementación específica de copyleft que se usa para la mayoría del software GNU es la Licencia Pública General de GNU (GNU General Public License) o LPG GNU para abreviar. La FSF tiene otras clases de copyleft que se usan en circunstancias específicas. Los manuales GNU también están bajo copyleft, pero se utiliza un copyleft mucho más simple, porque no es necesaria la complejidad de la LPG GNU para los manuales.

La licencia GNU GPL posibilita la modificación y redistribución del software, pero únicamente bajo esa misma licencia. Y añade que si se reutiliza en un mismo programa código «A» licenciado bajo licencia GNU GPL y código «B» licenciado bajo otro tipo de licencia libre, el código final «C», independientemente de la cantidad y calidad de cada uno de los códigos «A» y «B», debe estar bajo la licencia GNU GPL .

En la práctica esto hace que las licencias de software libre se dividan en dos grandes grupos, aquellas que pueden ser mezcladas con código licenciado bajo GNU GPL (y que inevitablemente desaparecerán en el proceso, al ser el código resultante licenciado bajo GNU GPL ) y las que no lo permiten al incluir mayores u otros requisitos que no contemplan ni admiten la GNU GPL y que por lo tanto no pueden ser enlazadas ni mezcladas con código gobernado por la licencia GNU GPL .

Esta situación de incompatibilidad, que podría ser resuelta en la próxima versión 3.0 de la licencia GNU GPL (en desarrollo), causa en estos momentos graves prejuicios a la comunidad de programadores de software libre, que muchas veces no pueden reutilizar o mezclar códigos de dos licencias distintas, pese a que las libertades teóricamente lo deberían permitir.

En el sitio web de la FSF hay una lista de licencias que cumplen las condiciones impuestas por la GNU GPL y otras que no.

En el sitio web de la OSI está la lista completa de las licencias de software libre actualmente aprobadas y tenidas como tales.