Questa pagina contiene i dettagli di un progetto di documentazione tecnica accettato per la stagione della documentazione di Google.
Riepilogo progetto
- Organizzazione open source:
- OpenMRS
- Technical Writer:
- Saurabh
- Nome del progetto:
- Estensione della documentazione di GitHub user-friendly per l'API REST
- Durata del progetto:
- Durata standard (3 mesi)
Project description
Obiettivo principale
Migliora la documentazione dell'API REST basata su Swagger di OpenMRS per aggiungere indicazioni sull'utilizzo dell'API.
Descrizione del progetto
L'API REST di OpenMRS è uno dei meccanismi chiave per consentire agli sviluppatori di accedere ai dati di OpenMRS. Esiste già una documentazione generata automaticamente basata su Swagger dell'API OpenMRS Webservices e una documentazione statica basata su GitHub. Dovremmo estendere questa documentazione basata su GitHub in questa stagione di Docs.
BREVE PANORAMICA
Dopo un po' di ricerche su OpenMRS Talk, come suggerito da Burke, ho scoperto che questo progetto è iniziato nel 2017 come progetto GSOC. Con Gayan Weerakutti, l'obiettivo principale era migliorare la documentazione esistente dell'API REST OpenMRS, migliorando la relativa specifica Swagger e il modo in cui viene generata, in modo da generare una versione migliore della documentazione Swagger stessa. Tutti i dettagli pertinenti raggiunti nel progetto sono stati riassunti qui in questo post del talk OpenMRS e sono stati molto utili.
Poi, nel 2019, questo progetto è stato rinnovato e abbiamo abbandonato le modifiche alla documentazione di Swagger che producevano varianti. Abbiamo invece sviluppato una documentazione statica compatibile con GitHub che estenderemo in questa stagione di Docs.
Ecco una breve descrizione della proposta di progetto attuale :
- Fornire esempi in alcuni linguaggi popolari (sono stati menzionati in particolare Java e JavaScript).
- Aggiunta del supporto di Playground per la documentazione di Slate, come la funzionalità di "prova" di Swagger.
- Rifactorizzazione e miglioramento del lavoro svolto finora.
- Trovare e aggiungere le risorse mancanti.
- Aggiunta di una descrizione più dettagliata alla sezione della console della documentazione
DESCRIZIONE DETTAGLIATA
- Fornisci esempi in lingue diverse.
Suggerirei di aggiungere esempi in Java basati su SDK e poi di aggiungere esempi di retrofit, che a mio avviso daranno maggiore profondità alla nostra documentazione. L'aggiunta di esempi in un altro linguaggio come JavaScript non sarà di grande aiuto come l'aggiunta di esempi di retrofit, perché ho utilizzato queste API REST mentre lavoravo al client Android OpenMRS e non c'erano risorse da consultare ogni volta che avevo bisogno di aiuto per utilizzare gli endpoint specifici per Android. E potrei fare degli esempi di qualità, dato che ho esperienza con gli endpoint dell'API OpenMRS nel client Android. Ne parlerò con i miei mentori e lavorerò su ciò che viene deciso. Inoltre, oltre ad aggiungere esempi per le operazioni supportate, dovremmo aggiungere esempi per l'autenticazione con i server OpenMRS anche in alcuni linguaggi di programmazione. Al momento abbiamo solo esempi curl per questo.
- Aggiunta del supporto di Playground per i test degli esempi di API
Ho utilizzato questa funzionalità nella documentazione di OpenMRS ospitata sul server di demo e si tratta di uno strumento davvero pratico da avere in qualsiasi documentazione dell'API. Ho fatto un po' di ricerche e non è così difficile incorporare la specifica Swagger-UI nella documentazione statica attuale. Utilizzando i pulsanti di attivazione/disattivazione di visualizzazione e l'attuale codice della documentazione di Swagger. In questo modo possiamo anche garantire che la funzionalità di prova rimanga attiva con le specifiche API attuali. Questo è uno dei modi in cui ritengo che potremmo integrare le funzionalità di Playground nella nostra attuale documentazione statica.
- Rifacimento e miglioramento del lavoro svolto finora
Controllo degli esempi di curl attuali
Questa sezione è uno degli aspetti principali di questo progetto per il 2020. Al momento, nelle API di GitHub sono presenti solo esempi di curl, alcuni dei quali non possono essere eseguiti direttamente sul server di demo per il controllo diretto dal browser. Testerò tutti gli endpoint attuali e manterrò un semplice documento con vari esempi di risposte di curl che riceviamo quando eseguiamo queste richieste. Se necessario, utilizzerò Postman oltre alla funzionalità di prova integrata nella documentazione di Swagger per completare questa attività.
Risposte dell'API mancanti in alcuni esempi
Alcune risposte sono state aggiunte per gli esempi di curl presenti, ma alcuni degli esempi di curl non hanno risposte. Penso che, anche se le risposte non sono dettagliate, come di solito accade con operazioni come l'eliminazione della risorsa, dovremmo avere un esempio di risposta dell'API JSON, anche se abbiamo documentato tutti i possibili codici di risposta e il motivo per cui ottenerli. Penso che questo renderebbe gli esempi nella documentazione dell'API più uniformi.
Mancano esempi di funzionamento su varie operazioni
Penso che questa sarà la parte più importante del refactoring del lavoro svolto in precedenza nella documentazione dell'API. La documentazione contiene esempi concreti che possono essere eseguiti direttamente con cURL, ma alcuni sono un po' astratti, il che fornisce un buon riferimento agli sviluppatori esperti, ma lascia perplessi i neofiti. Da questo post del talk di OpenMRS ho capito che i buoni esempi non hanno prezzo, quindi, oltre ad aggiungere esempi di lavoro, potremmo supportare l'evidenziazione della sintassi, che non richiede molto lavoro, perché è praticamente inclusa in Slate, il che rende l'operazione abbastanza facile, come ho scoperto qui,
Come Burke ha sottolineato molte volte nel suo post, preferendo la semplicità e la descrittività nella documentazione al posto di una buona interfaccia utente e di un'interfaccia accattivante, mi attengo a questi principi e cerco di rendere gli endpoint precedentemente documentati il più descrittivi possibile parlando con gli sviluppatori che stanno attualmente lavorando all'API OpenMRS Webservices e coinvolgendo la community, proprio come ho fatto nel post del talk per raccogliere le descrizioni dei tipi di attributi per le risorse dei moduli che non erano chiare nella mia RP qui. Mi concentrerei sulle priorità, parlerei con i miei mentor e deciderei quali sono gli aspetti che aggiungono davvero valore alla documentazione e devono essere completati per primi.
Aggiunta di Casi d'uso come titolo esplicito
Ho visto molta documentazione API solo per acquisire familiarità con queste API e ho notato che tutte avevano i casi d'uso come titolo esplicito, anche se abbiamo casi d'uso che non sono visibili esplicitamente, ma sono in qualche modo fusi all'interno delle definizioni e degli esempi che seguono le definizioni delle risorse e delle risorse secondarie. Penso che dovremmo fare lo sforzo di separare i casi d'uso come entità distinte nella documentazione in modo che gli sviluppatori non debbano davvero cercare nelle definizioni per dedurre i casi d'uso, ma possano semplicemente cercarli.
Trovare e documentare le risorse mancanti
Lo stato attuale del progetto elenca le risorse qui, ma dopo aver visto la versione più recente della documentazione di Swagger qui, ho potuto capire molte risorse che potrebbero essere aggiunte all'attuale suite di risorse nella documentazione dell'API GitHub con la descrizione come completata con altre risorse durante la Stagione della documentazione 2019. Parlerò degli argomenti che devono essere aggiunti ai documenti e li aggiungerò adeguatamente.
CONCLUSIONE
Faccio parte della community di OpenMRS da un po' di tempo. Contribuisci attivamente al progetto Android Client in cui interagisco spesso con le API per interagire con i server. Quindi, sento di poter lavorare su questo progetto di estensione dei documenti API piuttosto bene, dato che posso visualizzare il mio lavoro come sviluppatore e valutare se facilita davvero il lavoro di altri sviluppatori o meno, ho acquisito familiarità con gli strumenti utilizzati per il repository di documentazione di facile utilizzo ospitato qui, ho anche apportato diversi contributi a questo repository per acquisire familiarità con il repository e gli strumenti, poiché la sua API è considerata una buona documentazione
Mi assicurerò di comunicare gli avanzamenti settimanalmente con un post del talk, che mi aiuterà a ricevere il feedback della community e a lavorare in stretta collaborazione con il mio mentore e la community per ottenere il massimo da questo periodo di documentazione.