Esta es una guía para contribuir a la documentación oficial de la API de Discourse.
Nivel de usuario requerido: Desarrollador
Se requiere acceso a la consola
¿Quieres contribuir a la documentación oficial de la API en https://docs.discourse.org? Esta guía te explicará paso a paso cómo hacerlo.
Resumen
Esta documentación te guiará a través de los siguientes pasos:
- Configurar los requisitos previos.
- Clonar el repositorio de la documentación de la API de Discourse.
- Editar los archivos de documentación de la API.
- Visualizar tus cambios localmente.
- Crear un pull request.
Requisitos previos
Debes tener una instalación de desarrollo de Discourse. Si no tienes una, sigue la guía adecuada para tu entorno en estos temas.
Clonación del repositorio de documentación de la API de Discourse
Asumiendo que tu instalación de desarrollo de Discourse está dentro de tu directorio home ~/, procede con los siguientes pasos para clonar el repositorio:
-
Desde tu directorio home, clona el repositorio en https://github.com/discourse/discourse_api_docs:
git clone https://github.com/discourse/discourse_api_docs -
Ahora deberías tener las carpetas
discourseydiscourse_api_docsuna al lado de la otra:~/discourse/ ~/discourse_api_docs/
Edición de los archivos de documentación de la API
Debes editar la documentación directamente desde ~/discourse/spec/requests/api/.
- Ver la carpeta en GitHub: discourse/spec/requests/api at main · discourse/discourse · GitHub
La documentación de la API de plugins también se puede contribuir a través de archivos spec ubicados en plugins/*/spec/requests/api/.
Después de editar los archivos de documentación, ejecuta el siguiente comando desde ~/discourse/:
bin/rake rswag:specs:swaggerize && cp openapi/openapi.yaml ~/discourse_api_docs/openapi.yml
La documentación se generará utilizando rswag y se copiará en ~/discourse_api_docs/.
Luego, convierte el archivo YAML a JSON desde ~/discourse_api_docs/:
npm install
node tojson.js
Visualización de tus cambios localmente
Para ver tu documentación actualizada, sigue estos pasos:
-
Desde
~/discourse_api_docs/, ejecuta:npm install node server.js -
Navega a http://localhost:3001 para ver la documentación actualizada.
Creación de un pull request
Una vez que verifiques que todo esté correcto, crea un pull request desde el repositorio discourse/discourse (no desde el repositorio de Documentación de la API de Discourse).
El repositorio discourse_api_docs se actualiza automáticamente cada día mediante un flujo de trabajo de GitHub Actions que regenera la especificación OpenAPI a partir de las últimas especificaciones del núcleo de Discourse. No necesitas enviar un PR separado a ese repositorio.
Problemas comunes y soluciones
Reportar errores en la documentación de la API de Discourse
Si encuentras problemas o errores en la documentación de la API de Discourse, por favor repórtalos en el foro Meta de Discourse. Puedes seguir la guía de reportes de errores para ayudarte a hacerlo de manera efectiva.
¿Cuál parece ser el problema?