Contribuire alla documentazione dell'API Discourse

[Discourse]

Questa è una guida per contribuire alla documentazione ufficiale dell’API di Discourse.

Livello utente richiesto: Sviluppatore

Accesso alla console richiesto

Vuoi contribuire alla documentazione ufficiale dell’API su https://docs.discourse.org? Questa guida ti spiegherà passo dopo passo come farlo.

Riepilogo

Questa documentazione ti guiderà attraverso i seguenti passaggi:

• Configurazione dei prerequisiti.
• Clonazione del repository della documentazione API di Discourse.
• Modifica dei file di documentazione dell’API.
• Visualizzazione delle modifiche in locale.
• Creazione di una pull request.

Prerequisiti

Devi avere un’installazione di sviluppo di Discourse. Se non ne hai una, segui la guida adatta al tuo ambiente in questi argomenti.

Clonazione del repository della documentazione API di Discourse

Supponendo che la tua installazione di sviluppo di Discourse si trovi nella tua home directory ~/, procedi con i seguenti passaggi per clonare il repository:

1. Dalla tua home directory, clona il repository all’indirizzo https://github.com/discourse/discourse_api_docs:

   git clone https://github.com/discourse/discourse_api_docs
   

2. Ora dovresti avere le cartelle discourse e discourse_api_docs una accanto all’altra:

   ~/discourse/
   ~/discourse_api_docs/
   

Modifica dei file di documentazione dell’API

Devi modificare la documentazione direttamente da ~/discourse/spec/requests/api/.

• Vedi la cartella su GitHub: discourse/spec/requests/api at main · discourse/discourse · GitHub

La documentazione dell’API dei plugin può essere contribuita anche tramite file spec situati in plugins/*/spec/requests/api/.

Dopo aver modificato i file di documentazione, esegui il seguente comando da ~/discourse/:

bin/rake rswag:specs:swaggerize && cp openapi/openapi.yaml ~/discourse_api_docs/openapi.yml

La documentazione verrà generata utilizzando rswag e copiata in ~/discourse_api_docs/.

Quindi, converti il file YAML in JSON da ~/discourse_api_docs/:

npm install
node tojson.js

Visualizzazione delle modifiche in locale

Per visualizzare la tua documentazione aggiornata, segui questi passaggi:

1. Da ~/discourse_api_docs/, esegui:

   npm install
   node server.js
   

2. Apri il browser su http://localhost:3001 per vedere la documentazione aggiornata.

Creazione di una pull request

Una volta verificato che tutto sia corretto, crea una pull request dal repository discourse/discourse (non dal repository Discourse API Docs).

Il repository discourse_api_docs viene aggiornato automaticamente ogni giorno tramite un flusso di lavoro GitHub Actions che rigenera la specifica OpenAPI dalle ultime specifiche core di Discourse. Non è necessario inviare una PR separata a quel repository.

Problemi comuni e soluzioni

Segnalazione di errori nella documentazione API di Discourse

Se incontri problemi o errori nella documentazione API di Discourse, segnalali sul forum Meta di Discourse - puoi seguire la guida per la segnalazione di bug per aiutarti a farlo in modo efficace.

Risorse aggiuntive

• Topics tagged dev-install
• Repository GitHub di Discourse

[srinivas.chilukuri]

Come segnalare errori nella documentazione dell’API di discourse

Il repository Github per la documentazione dell’API non ha la scheda issues attivata

[JammyDodger]

Ciao e benvenuto @srinivas.chilukuri
Puoi segnalarli qui. Qual è il problema?

[srinivas.chilukuri]

Riferimento: Documentazione API Discourse Ottieni un gruppo

Azioni: Gruppi/ Ottieni un gruppo

• Nel parametro del percorso della documentazione è mostrato come id, quando interrogato il percorso non esiste
• Quando la stessa query è stata retroingegnerizzata tramite l’interfaccia utente di Discourse, il parametro del percorso è il nome del gruppo e lo stesso funziona tramite API Key