Questa pagina contiene i dettagli di un progetto di documentazione tecnica accettato per la stagione della documentazione di Google.
Riepilogo del progetto
- Organizzazione open source:
- OpenMRS.org
- Redattore tecnico:
- batbrain7
- Nome del progetto:
- Documentazione dell'API REST OpenMRS
- Durata del progetto:
- Durata standard (3 mesi)
Project description
Suddividerò la mia proposta in sezioni diverse e seguirò il flusso come la documentazione dell'API di Google Maps e la documentazione dell'API di GitHub.
A parte questo, vorrei anche proporre una struttura readme per la documentazione dell'API creata da realworld.io: https://github.com/gothinkster/realworld/tree/master/api
Personalmente, ho trovato questa documentazione molto facile da capire e utilizzare.
La mia proposta è composta principalmente da tre sezioni :
Una sezione che fornisca una breve introduzione all'API, a OpenMRS e a come viene utilizzata l'API e a cosa segue.
Come ottenere la chiave API e l'autenticazione necessaria in generale per effettuare la richiesta API. Sarà un esempio di tipi di autenticazione presenti nell'API, nonché delle chiavi e dei valori che devono essere presenti per l'autenticazione, oltre ai tipi di valori accettati corrispondenti alla chiave in quella parte. Un esempio di codice in qualsiasi lingua sarebbe utile per capire come scrivere le intestazioni, i formati di risposta e altri parametri di query nell'API.
Devono essere menzionati i tipi di risposte recuperate dall'API, i tipi di JSON o qualsiasi altro tipo di risultato restituito dalle API.
Le diverse route API e ciò che tutti i parametri devono essere inviati insieme a quelli, le intestazioni e altro ancora. Per ogni API saranno disponibili esempi di codice in alcuni linguaggi che descrivono come viene effettuata la richiesta durante la scrittura del codice. Inoltre, devono essere menzionati i codici di errore generali che potrebbero verificarsi con ogni API.
Questa è un'idea generale di come verrà definita la documentazione per l'API REST.
La pianificazione del progetto è la seguente :
1 agosto - 1° settembre
Familiarizza con il mio mentore e discuti più a fondo il livello di documentazione richiesto nelle diverse parti del codebase e discuti l'approfondimento della documentazione di basso livello rispetto a quella di alto livello. Inoltre, userò questo tempo per comprendere la base di codice e studiare i concetti in modo da poterli documentare meglio.
Settimane 1 e 2
Aggiornerò e amplierò la guida per i collaboratori. Migliorerò la documentazione su come creare il codice sorgente. Aggiungerò anche una sezione di documentari su come i nuovi collaboratori possono aiutare nella documentazione. Studierò la documentazione delle diverse API e inizierò con l'introduzione e aggiungerò l'autenticazione per l'API.
Settimana 3-8
Aggiungerò le route e le risposte dell'API insieme ad alcuni esempi di codice per ogni tipo di API (potrebbero esserci tipi di API simili).
Settimana 9 e 10
Aggiungi la struttura della documentazione dell'API utilizzando i link, ad esempio un indice collegato per la documentazione dell'API lunga, e suddividila ulteriormente in base a criteri diversi, come sezioni di codice, panoramica, parametri, endpoint principali.
Settimana finale
Utilizzerò l'ultima settimana per preparare il report finale del lavoro svolto durante il periodo di documentazione di 12 settimane. Inoltre, ne approfitterò per rivedere e finalizzare la documentazione.