Questa pagina contiene i dettagli di un progetto di scrittura tecnica accettato per la stagione dei documenti Google.
Riepilogo del progetto
- Organizzazione open source:
- OpenMRS
- Technical writer:
- Saurabh
- Nome progetto:
- Estensione della documentazione GitHub di facile utilizzo per l'API REST
- Durata del progetto:
- Durata standard (3 mesi)
Project description
Obiettivo principale
Migliora la documentazione dell'API REST basata su OpenMRS Swagger per aggiungere indicazioni sull'uso dell'API.
Descrizione progetto
L'API REST OpenMRS è uno dei meccanismi chiave per gli sviluppatori per accedere ai dati da OpenMRS. Esiste già una documentazione generata automaticamente e basata su Swagger per l'API OpenMRS Webservices e una documentazione statica basata su GitHub; dovremmo estendere questa documentazione basata su GitHub in questa stagione di Documenti.
BREVE PANORAMICA
Dopo alcune ricerche su OpenMRS Talk come ha suggerito Burke, ho scoperto che questo progetto è iniziato nel 2017 come progetto GSOC. Con Gayan Weerakutti, il cui obiettivo principale era migliorare la documentazione esistente dell'API REST OpenMRS, migliorando la specifica Swagger e la modalità di generazione della specifica Swagger in modo da generare una versione migliore della stessa documentazione spavalda. Tutti i dettagli rilevanti realizzati nel progetto sono stati riassunti qui in questo post di discussione di OpenMRS e sono stati molto utili.
Poi, nel 2019, questo progetto è stato rinnovato e siamo passati dalle modifiche alla documentazione di Swagger che ne hanno prodotto delle variazioni. Abbiamo invece sviluppato una documentazione statica compatibile con GitHub che estenderemo in questa stagione di Documenti.
Quindi, un breve riassunto dell'attuale proposta di progetto che intendo descrivere è :
- Ho trovato esempi in alcuni linguaggi diffusi (ad esempio Java e JavaScript).
- Aggiunta del supporto Playground per la documentazione di slate, proprio come la funzionalità ""try-out"" di carattere spavaldo.
- Refactoring e miglioramento del lavoro svolto finora.
- Ricerca e aggiunta delle risorse mancanti.
- Aggiunta di qualche informazione in più alla sezione della console della documentazione
DESCRIZIONE DETTAGLIATA
- Prepara esempi in diverse lingue.
Suggerirei di aggiungere esempi in Java che saranno basati su SDK e poi di aggiungere esempi di retrofit che penso aggiungeranno più profondità alla nostra documentazione, poiché l'aggiunta di esempi in un altro linguaggio come JavaScript non sarà di aiuto quanto aggiungere esempi di retrofit poiché ho utilizzato queste API REST mentre lavoro sul client Android OpenMRS e non c'erano risorse a cui cercare ogni volta che ho bisogno di aiuto con gli endpoint specifici per Android. Potrei fare sul serio alcuni esempi di qualità qui data la mia esperienza con gli endpoint dell'API OpenMRS nel client Android. Ne parlerò con i miei mentori e lavorerò alle decisioni. Inoltre, oltre ad aggiungere esempi per le operazioni supportate, dovremmo aggiungere anche esempi per l'autenticazione con i server OpenMRS in alcuni linguaggi di programmazione. Al momento abbiamo solo esempi di curl per questo.
- Aggiunta del supporto di Playground per esempi di API di test
Ho utilizzato questa funzione nella documentazione spavalda di OpenMRS ospitata sul server demo ed è uno strumento davvero comodo da avere in qualsiasi documentazione dell'API. Ho fatto qualche ricerca qui e non è così difficile incorporare le specifiche dell'UI Swagger nell'attuale documentazione statica. Usare i pulsanti di attivazione/disattivazione per mostrare o nascondere i contenuti e l'attuale codice della documentazione a scopo di spavalderia. In questo modo possiamo persino garantire che la funzionalità di prova rimanga attiva con le specifiche API attuali. Questo è un modo che credo che potremmo integrare nella nostra attuale documentazione statica.
- Refactoring e miglioramento del lavoro svolto finora
Controllo degli esempi di curl correnti in corso...
Questa sezione è uno dei principali argomenti di questo progetto quest'anno. Attualmente, nei documenti dell'API GitHub sono presenti solo esempi di curl, alcuni dei quali non possono essere eseguiti direttamente sul server demo per il controllo direttamente dal browser. Testerò tutti gli endpoint attuali e gestirò un semplice documento con varie risposte di esempi di curl che riceviamo durante l'esecuzione delle richieste curl. Utilizzerò Postman in aggiunta alla funzionalità di prova integrata nella documentazione audace per portare a termine questa attività, se necessario.
Risposte dell'API mancanti su 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 siano dettagliate, che di solito è il caso con operazioni come l'eliminazione definitiva della risorsa, dovremmo avere una risposta dell'API JSON di esempio anche se abbiamo documentato tutti i possibili codici di risposta e il motivo per riceverli, penso che questo renderebbe più uniformi gli esempi nella documentazione dell'API !!
Esempi di funzionamento mancanti in varie operazioni
Penso che questa sarà la parte più importante del refactoring del lavoro svolto in precedenza nella documentazione dell'API; ci sono esempi concreti nella documentazione che possono essere eseguiti direttamente con cURL, ma alcuni sono un po' astratti, il che fornisce un buon riferimento a sviluppatori esperti, ma lascia i nuovi arrivati in uno stato di seccatura. Come ho potuto constatare da questo post di OpenMRS che i buoni esempi sono inestimabili, quindi oltre all'aggiunta di esempi di lavoro potremmo supportare la sintassi che evidenzia che non è molto lavoro, ma viene fornito in bundle con slate che rende tutto facile da fare, come ho scoperto qui,
Come ha sottolineato molte volte nel suo post burke a preferire la semplicità e la descrizione nei documenti al posto di una buona interfaccia utente e di un'interfaccia brillante, cercherei di rispettare questi principi e di cercare di rendere gli endpoint documentati in precedenza il più possibile descrittivi parlando con gli sviluppatori che stanno attualmente lavorando all'API dei servizi web OpenMRS e coinvolgendo la community, proprio come ho fatto nel post della discussione per la raccolta delle descrizioni dei tipi di attributi per le risorse dei moduli che non mi erano chiare qui. Mi occuperò davvero di priorità, parlando con i miei mentori e decidendo quali sono le cose che apportano un valore reale ai documenti e che devono essere completate per prime.
Aggiungere i casi d'uso come titolo esplicito
Ho visto molte documentazioni sulle API solo per prendere confidenza e ho visto che tutte avevano casi d'uso come titolo esplicito, anche se ci sono casi d'uso che non sono esplicitamente visibili, ma sono in qualche modo fusi all'interno delle definizioni e degli esempi che seguono dopo le definizioni delle risorse e delle sottorisorse. Penso che dovremmo cercare di separare i casi d'uso come entità separate nella documentazione, in modo che gli sviluppatori non debbano limitarsi a cercare le definizioni.
Trovare e documentare le risorse mancanti
Lo stato attuale del progetto ha risorse elencate qui, ma vedendo l'ultima versione della documentazione spavaldo qui, ho potuto capire molte risorse che potrebbero essere aggiunte alla suite attuale di risorse nei documenti dell'API GitHub amichevole con la descrizione come realizzato con altre risorse durante la stagione di Docs 2019. Parlerò degli argomenti che devono essere aggiunti ai documenti e li aggiungerò correttamente.
CONCLUSIONE
Faccio parte della community OpenMRS da un po' di tempo. Contribuisci attivamente al progetto client Android, in cui interagisco spesso con le API per interagire con i server. Quindi, ritengo di poter lavorare su questo progetto di estensione dei documenti API perché io posso visualizzare il mio lavoro come sviluppatore e valutare se semplifica 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 apportato diversi contributi anche a questo repository per acquisire familiarità con il repository e gli strumenti, ad es.
Farò in modo di comunicare i progressi ogni settimana con un post di discussione che aiuterà a ottenere il feedback dalla community e a lavorare a stretto contatto con il mio mentore e la community per ottenere il meglio da questo periodo di documentazione.