¿Cómo puedo contribuir a la especificación OpenAPI? #

Contribuir a la especificación OpenAPI (OAS) es una forma significativa de influir en el futuro del desarrollo de API. Al ser un proyecto de código abierto, la OAS se beneficia de los esfuerzos colaborativos de desarrolladores, redactores técnicos y colaboradores de todo el mundo. Si te interesa participar pero no sabes por dónde empezar, este artículo recorre los pasos esenciales, desde comprender qué es la OAS hasta las formas prácticas de involucrarte.

Comprender la especificación OpenAPI #

La especificación OpenAPI es un estándar de acceso público que permite a los desarrolladores definir la interfaz de sus API. Conocida originalmente como la especificación Swagger, ofrece una forma estructurada de describir las API, lo que facilita la interoperabilidad y promueve las buenas prácticas en el diseño de API. Las contribuciones a la OAS ayudan a mejorar la especificación y su ecosistema, haciendo que sea más fácil para los desarrolladores adoptarla e implementarla.

Pasos para contribuir #

1. Familiarízate con el proyecto #

Antes de empezar a contribuir, es esencial entender qué es la OAS y cómo funciona. Algunos recursos relevantes son:

• Repositorio de la especificación OpenAPI en GitHub: es el repositorio principal en el que contribuirás. Revisa la documentación, las incidencias (issues) actuales y los pull requests (PR).
• OpenAPI Initiative: el sitio oficial ofrece información detallada sobre la especificación, incluidos su historia, su modelo de gobernanza y las herramientas compatibles.
• Swagger.io: aunque OpenAPI y Swagger son cosas distintas, las herramientas de Swagger admiten la OAS y son recursos útiles para comprender las aplicaciones prácticas de la especificación.

2. Únete a la comunidad #

Formar parte de la comunidad te ayuda a mantenerte al día de las novedades, recibir ayuda e interactuar con otros colaboradores. Algunas formas de participar son:

• Listas de correo: únete a las listas de correo de la OpenAPI Initiative para participar en los debates y consultar los anuncios.
• Slack: muchos proyectos de código abierto usan Slack para comunicarse. Comprueba si existe un canal de Slack para la OAS y únete para empezar a interactuar con otros miembros.
• Reuniones: asiste a las reuniones del Comité Directivo Técnico (TSC) de la OAS y de los grupos de trabajo. Son espacios donde se toman y se anuncian las decisiones clave.

3. Elige tu área de contribución #

Hay varias formas de contribuir, según tus habilidades e intereses:

• Documentación: mejorar y ampliar la documentación es fundamental para cualquier proyecto de código abierto. Busca carencias en la documentación o áreas que requieran aclaraciones.
• Contribuciones de código: si eres desarrollador, considera contribuir con código. Esto puede implicar corregir errores, añadir funcionalidades o mejorar las existentes.
• Revisión de PR: revisar las contribuciones de otras personas ayuda a mantener la calidad del proyecto y aporta una perspectiva nueva sobre los cambios propuestos.
• Propuesta de nuevas funcionalidades: si tienes ideas para mejorar la OAS, puedes proponer nuevas funcionalidades. Asegúrate de que tus propuestas estén alineadas con la hoja de ruta del proyecto y beneficien a la comunidad en general.
• Evangelización y difusión: promueve el uso de la OAS en tu organización o en eventos del sector. Escribir artículos, dar charlas y crear tutoriales ayuda a aumentar la concienciación y la adopción.

4. Configura tu entorno #

Antes de contribuir con código, tendrás que configurar un entorno de desarrollo local:

1. Haz un fork del repositorio: haz un fork del repositorio de la especificación OpenAPI en tu cuenta de GitHub.
2. Clona tu fork: clona tu fork en tu máquina local con git clone.
3. Configura las dependencias: sigue las instrucciones de configuración que se indiquen en la documentación del repositorio para instalar las dependencias necesarias.

5. Atiende incidencias #

Identificar y atender incidencias es una forma sencilla de contribuir:

• Explora las incidencias: consulta la sección de incidencias del repositorio de GitHub para encontrar tareas que requieran atención. Busca etiquetas como good first issue o help wanted si eres nuevo en el proyecto.
• Reclama una incidencia: comenta en la incidencia que te interese para que otros sepan que estás trabajando en ella y evitar duplicar esfuerzos.
• Envía un pull request: una vez que hayas realizado tus cambios, envía un PR. Sigue de cerca las directrices de contribución, ya que pueden contener instrucciones específicas para estructurar y enviar tu PR.

6. Propón cambios #

Si quieres proponer un cambio o una funcionalidad importante:

• Crea una incidencia o un debate en GitHub: antes de escribir código, comenta tu idea para recabar opiniones y asegurarte de que está alineada con los objetivos del proyecto.
• Envía un PR en borrador: a veces, ver el código ayuda en las conversaciones. Los PR en borrador son una buena forma de compartir trabajo en curso y obtener comentarios tempranos.
• Colabora e itera: trabaja con los revisores para perfeccionar tus cambios. Muéstrate receptivo a los comentarios y dispuesto a hacer ajustes.

7. Haz el seguimiento #

No se trata solo de enviar código o documentación, sino también de asegurarse de que se revise y se fusione. Lleva un registro de tus contribuciones y haz el seguimiento necesario:

• Responde a los comentarios: participa en los comentarios y realiza con prontitud los cambios necesarios.
• Actualiza la documentación: refleja tus cambios en la documentación para ayudar a otros usuarios a comprender las nuevas funcionalidades o modificaciones.
• Celebra los hitos: reconoce tus contribuciones compartiéndolas con la comunidad y celebrando los hitos alcanzados.

8. Mantente al día #

La OAS evoluciona continuamente, por lo que es esencial mantenerse al día de los últimos cambios:

• Sigue el repositorio: en GitHub puedes suscribirte al repositorio (watch) para recibir notificaciones sobre nuevas incidencias, PR y debates.
• Asiste a las reuniones de la comunidad: participar con regularidad en las reuniones te ayuda a estar informado y a implicarte en la dirección del proyecto.
• Sigue las novedades: consulta el blog de la especificación OpenAPI u otros canales de comunicación para ver los anuncios.

Conclusión #

Contribuir a la especificación OpenAPI es una labor gratificante que ofrece la oportunidad de colaborar con una comunidad global y dar forma al futuro del desarrollo de API. Con una comprensión clara del proceso, una participación activa en la comunidad y el compromiso de hacer el seguimiento, puedes realizar contribuciones sustanciales que beneficien a desarrolladores de todo el mundo.

Ya sea escribiendo documentación, corrigiendo errores, revisando propuestas o promoviendo la especificación, cada contribución es valiosa. Recuerda que los proyectos de código abierto prosperan gracias a la colaboración, la diversidad de ideas y el esfuerzo colectivo de sus colaboradores.

Para profundizar y obtener orientación sobre cómo iniciar tu camino con la OAS, consulta la guía de contribución de la OpenAPI Initiative.

¡Feliz contribución!

Última actualización: 21 de mayo de 2024.