Documentazione sull'API in linea

Questa sezione fornisce le linee guida per aggiungere documentazione incorporata all'API. La maggior parte delle API dispone anche di panoramiche, tutorial e documentazione di riferimento di livello superiore, che esulano dall'ambito di questa Guida alla progettazione. Per informazioni sulla denominazione di API, risorse e metodi, consulta la pagina relativa alle convenzioni di denominazione.

Formato dei commenti nei file proto

Aggiungi commenti al file .proto utilizzando il solito formato di commento // dei buffer di protocollo.

// Creates a shelf in the library, and returns the new Shelf.
rpc CreateShelf(CreateShelfRequest) returns (Shelf) {
  option (google.api.http) = { post: "/v1/shelves" body: "shelf" };
}

Commenti nella configurazione del servizio

In alternativa all'aggiunta di commenti della documentazione al file .proto, puoi aggiungere documentazione incorporata alla tua API nel relativo file di configurazione del servizio YAML. La documentazione in questo file avrà la precedenza sulla documentazione in .proto se lo stesso elemento è documentato in entrambi i file.

documentation:
  summary: Gets and lists social activities
  overview: A simple example service that lets you get and list possible social activities
  rules:
  - selector: google.social.Social.GetActivity
    description: Gets a social activity. If the activity does not exist, returns Code.NOT_FOUND.
...

Potrebbe essere necessario utilizzare questo approccio se disponi di più servizi che utilizzano gli stessi file .proto e vuoi fornire la documentazione specifica del servizio. Le regole della documentazione YAML ti consentono anche di aggiungere un elemento overview più dettagliato alla descrizione dell'API. Tuttavia, in generale è preferibile aggiungere commenti alla documentazione a .proto.

Come per i commenti .proto, puoi utilizzare Markdown per fornire un'ulteriore formattazione nei commenti del file YAML.

Descrizione API

La descrizione dell'API è una frase che inizia con un verbo attivo che descrive cosa puoi fare con l'API. Nel file .proto viene aggiunta una descrizione dell'API come commento al service corrispondente, come nell'esempio seguente:

// Manages books and shelves in a simple digital library.
service LibraryService {
...
}

Di seguito sono riportati alcuni esempi di descrizioni dell'API:

• Condivide aggiornamenti, foto, video e altro ancora con i tuoi amici in tutto il mondo.
• Accede a un servizio di machine learning ospitato nel cloud che semplifica la creazione di app intelligenti che rispondono a flussi di dati.

Descrizione risorsa

La descrizione di una risorsa è una frase parziale che descrive cosa rappresenta la risorsa. Se devi aggiungere ulteriori dettagli, utilizza frasi aggiuntive. Nel file .proto, viene aggiunta una descrizione della risorsa come commento al tipo di messaggio corrispondente, come nell'esempio seguente:

// A book resource in the Library API.
message Book {
  ...
}

Ecco alcuni esempi di descrizioni delle risorse:

• Un'attività nell'elenco di cose da fare dell'utente. Ogni attività ha una priorità univoca.
• Un evento nel calendario dell'utente.

Descrizioni di campi e parametri

Una frase sostantivo che descrive un campo o una definizione di parametro, come mostrato nei seguenti esempi:

• Il numero di argomenti di questa serie.
• Precisione in metri delle coordinate di latitudine e longitudine. Deve essere un numero non negativo.
• Flag che stabilisce se i valori dell'URL dell'allegato vengono restituiti per le risorse di invio di questa serie. Il valore predefinito di series.insert è true.
• Il contenitore per le informazioni sulle votazioni. Presente solo quando sono registrate le informazioni sulle votazioni.
• Attualmente non in uso o deprecato.

Le descrizioni di campi e parametri devono descrivere i valori validi e non validi. Ricorda che gli ingegneri faranno del loro meglio per interrompere qualsiasi servizio e non saranno in grado di leggere il codice sottostante per chiarire eventuali informazioni non chiare.

Per le stringhe, la descrizione deve descrivere la sintassi e i caratteri consentiti, nonché l'eventuale codifica obbligatoria. Ad esempio:

• 1-255 caratteri nel set [A-a0-9]
• Una stringa di percorso dell'URL valida che inizia con / che segue le convenzioni RFC 2332. La lunghezza massima è di 500 caratteri.

La descrizione deve specificare qualsiasi valore o comportamento predefinito, ma potrebbe omettere la descrizione dei valori predefiniti che in realtà sono nulli.

Se il valore del campo è obbligatorio, solo input o solo output, dovrebbe essere documentato all'inizio della descrizione del campo. Per impostazione predefinita, tutti i campi e i parametri sono facoltativi. Ad esempio:

message Table {
  // Required. The resource name of the table.
  string name = 1;

  // Input only. Whether to validate table creation without actually doing it.
  bool validate_only = 2;

  // Output only. The timestamp when the table was created. Assigned by
  // the server.
  google.protobuf.Timestamp create_time = 3;

  // The display name of the table.
  string display_name = 4;
}

Nota: le descrizioni dei campi devono fornire un valore di esempio ogni volta che è fattibile e utile.

Descrizione del metodo

Una descrizione del metodo è una frase che indica l'effetto del metodo e la risorsa su cui opera. Solitamente inizia con un verbo presente in terza persona, ovvero un verbo che termina con "s" in inglese. Se devi aggiungere ulteriori dettagli, usa frasi aggiuntive. Ecco alcuni esempi:

• Elenca gli eventi di calendario per l'utente autenticato.
• Aggiorna un evento di calendario con i dati inclusi nella richiesta.
• Elimina un record della posizione dalla cronologia delle posizioni dell'utente autenticato.
• Crea o aggiorna un record di posizione nella cronologia delle posizioni dell'utente autenticato utilizzando i dati inclusi nella richiesta. Se esiste già una risorsa di località con lo stesso valore di timestamp, i dati forniti sovrascrivono quelli esistenti.

Elenco di controllo per tutte le descrizioni

Assicurati che ogni descrizione sia breve, ma completa e comprensibile agli utenti che non hanno informazioni aggiuntive sull'API. Nella maggior parte dei casi, c'è altro da dire oltre alla semplice riaffermazione dell'ovvio; ad esempio, la descrizione del metodo series.insert non dovrebbe limitarsi a "Inserisci una serie". Anche se i nomi dovrebbero essere ricchi di informazioni, la maggior parte dei lettori legge le descrizioni perché vogliono più informazioni rispetto ai nomi forniti. Se non sai cos'altro dire in una descrizione, prova a rispondere a tutte le seguenti domande pertinenti:

• Che cos'è?
• Che cosa fa se l'operazione riesce? Che cosa fa se non va a buon fine? Cosa può causare l'errore e come?
• È idempotente?
• Quali sono le unità? Esempi: metri, gradi, pixel.
• Quale intervallo di valori accetta? L'intervallo è inclusivo o esclusivo?
• Quali sono gli effetti collaterali?
• Come lo usi?
• Quali sono gli errori comuni che possono causare errori?
• È sempre presente? Ad esempio: "Contenitore per le informazioni di voto. Presente solo quando vengono registrate le informazioni sulle votazioni.")
• Ha un'impostazione predefinita?

Convenzioni

Questa sezione elenca alcune convenzioni di utilizzo per le descrizioni testuali e la documentazione. Ad esempio, utilizza "ID" (tutto in maiuscolo) anziché "Id" o "id" quando parli di identificatori. Utilizza "JSON" anziché "Json" o "json" quando fai riferimento a questo formato dati. Mostra tutti i nomi di campi/parametri in code font. Inserisci i valori stringa letterali tra code font e virgolette.

• ID
• JSON
• RPC
• REST
• property_name o "string_literal"
• true/false

Livelli dei requisiti

Per impostare le aspettative o i livelli dei requisiti relativi allo stato, utilizza i termini: Must, Must not, required, shall, shall not, meta, costante, recommended, may e optional.

I significati sono definiti nel documento RFC 2119. Potresti voler includere l'istruzione dell'estratto RFC nella documentazione dell'API.

Stabilisci quale termine soddisfa i tuoi requisiti offrendo al contempo flessibilità agli sviluppatori. Non usare termini assoluti come need quando altre opzioni funzionano tecnicamente nella tua API.

Stile lingua

Come nelle nostre convenzioni di denominazione, consigliamo di utilizzare un vocabolario e uno stile semplici e coerenti quando scrivi i commenti ai documenti. I commenti devono essere comprensibili per i lettori che non parlano inglese, quindi evita gergo, slang, metafore complesse, riferimenti alla cultura pop o qualsiasi altra cosa che non sia facile da tradurre. Utilizza uno stile amichevole e professionale che si rivolga direttamente agli sviluppatori che leggono i tuoi commenti e mantieni il più conciso possibile. Ricorda che la maggior parte dei lettori vuole scoprire come fare qualcosa con la tua API, non leggere la documentazione.