Dies ist eine Anleitung zum Beitrag zur offiziellen Discourse-API-Dokumentation.
Erforderliche Benutzerstufe: Entwickler
Zugriff auf die Konsole erforderlich
Möchtest du zur offiziellen API-Dokumentation unter https://docs.discourse.org beitragen? Diese Anleitung erklärt Schritt für Schritt, wie du das tun kannst.
Zusammenfassung
Diese Dokumentation führt dich durch folgende Schritte:
- Einrichten der Voraussetzungen.
- Klonen des Discourse-API-Dokumentations-Repositories.
- Bearbeiten der API-Dokumentationsdateien.
- Lokales Anzeigen deiner Änderungen.
- Erstellen eines Pull-Requests.
Voraussetzungen
Du musst eine Discourse-Entwicklungsumgebung installiert haben. Falls nicht, folge der Anleitung, die zu deiner Umgebung passt, in diesen Themen.
Klonen des Discourse-API-Docs-Repositories
Angenommen, deine Discourse-Entwicklungsumgebung befindet sich in deinem Home-Verzeichnis ~/, gehe wie folgt vor, um das Repository zu klonen:
-
Klonen des Repositories von deinem Home-Verzeichnis aus unter https://github.com/discourse/discourse_api_docs:
git clone https://github.com/discourse/discourse_api_docs -
Du solltest nun die Ordner
discourseunddiscourse_api_docsnebeneinander haben:~/discourse/ ~/discourse_api_docs/
Bearbeiten der API-Dokumentationsdateien
Du musst die Dokumentation direkt unter ~/discourse/spec/requests/api/ bearbeiten.
- Sieh dir den Ordner auf GitHub an: discourse/spec/requests/api at main · discourse/discourse · GitHub
Die Plugin-API-Dokumentation kann ebenfalls über Spec-Dateien in plugins/*/spec/requests/api/ beigetragen werden.
Nachdem du die Dokumentationsdateien bearbeitet hast, führe folgenden Befehl von ~/discourse/ aus:
bin/rake rswag:specs:swaggerize && cp openapi/openapi.yaml ~/discourse_api_docs/openapi.yml
Die Dokumentation wird mit rswag generiert und nach ~/discourse_api_docs/ kopiert.
Konvertiere dann die YAML-Datei von ~/discourse_api_docs/ aus in JSON:
npm install
node tojson.js
Lokales Anzeigen deiner Änderungen
Um deine aktualisierte Dokumentation anzuzeigen, folge diesen Schritten:
-
Führe von
~/discourse_api_docs/aus Folgendes aus:npm install node server.js -
Öffne http://localhost:3001, um die aktualisierte Dokumentation zu sehen.
Erstellen eines Pull-Requests
Sobald du überprüft hast, dass alles in Ordnung ist, erstelle einen Pull-Request aus dem discourse/discourse-Repository (nicht dem Discourse API Docs-Repository).
Das discourse_api_docs-Repository wird täglich automatisch über einen GitHub Actions-Workflow aktualisiert, der die OpenAPI-Spezifikation aus den neuesten Discourse-Core-Specs neu generiert. Du musst keinen separaten PR an dieses Repository senden.
Häufige Probleme und Lösungen
Fehler in der Discourse-API-Dokumentation melden
Wenn du Probleme oder Fehler in der Discourse-API-Dokumentation feststellst, melde sie bitte im Discourse Meta-Forum. Du kannst den Anleitung zum Melden von Fehlern befolgen, um dies effektiv zu tun.
Was scheint das Problem zu sein?