Documentazione sull'API in linea

Questa sezione fornisce le linee guida per l'aggiunta di documentazione in linea al tuo tramite Google Cloud CLI o tramite l'API Compute Engine. La maggior parte delle API include anche panoramiche, tutorial e documentazione di riferimento di livello superiore, che non rientrano nell'ambito di questa Guida alla progettazione. Per informazioni sulla denominazione di API, risorse e metodi, consulta la sezione Denominazione. convenzioni.

Formato dei commenti nei file proto

Aggiungi commenti al file .proto utilizzando il solito formato dei commenti di Protocol Buffers //.

// 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 alla documentazione in .proto puoi aggiungere la documentazione incorporata all'API nel suo servizio YAML di configurazione del deployment. La documentazione di 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.
...

Potresti dover utilizzare questo approccio se hai più servizi che utilizzano gli stessi file .proto e vuoi fornire documentazione specifica per ciascun servizio. Le regole della documentazione YAML consentono anche di aggiungere overview alla descrizione dell'API. Tuttavia, in generale è preferibile aggiungere commenti alla documentazione del .proto.

Come per i commenti .proto, puoi utilizzare Markdown per fornire ulteriori 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, una descrizione dell'API viene aggiunta come commento al service corrispondente, come nell'esempio seguente:

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

Ecco altri esempi di descrizioni dell'API:

• Condividi aggiornamenti, foto, video e altro ancora con i tuoi amici nelle vicinanze nel mondo.
• Accede a un servizio di machine learning ospitato nel cloud che semplifica per creare app intelligenti che rispondono ai flussi di dati.

Descrizione della risorsa

Una descrizione della risorsa è una frase parziale che descrive cosa rappresenta la risorsa. Se hai bisogno di aggiungere ulteriori dettagli, utilizza altre frasi. Nel file .proto, una descrizione della risorsa viene aggiunta 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 di 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 nominale che descrive una definizione di campo o parametro, come mostrato nei seguenti esempi:

• Il numero di argomenti di questa serie.
• La precisione delle coordinate di latitudine e longitudine, in metri. Deve essere un numero non negativo.
• Indica se i valori degli URL degli allegati vengono restituiti per le risorse di invio in questa serie. Il valore predefinito per series.insert è true.
• Il contenitore delle informazioni sulle votazioni. Presente solo quando vengono registrate le informazioni sul voto.
• Non in uso o deprecato.

Le descrizioni dei campi e dei parametri devono descrivere quali valori sono validi e non validi. Ricorda che i tecnici faranno del loro meglio per interrompere qualsiasi servizio e non è in grado di leggere il codice sottostante per chiarire eventuali informazioni poco chiare.

Per le stringhe, la descrizione deve descrivere la sintassi e le caratteri e qualsiasi codifica richiesta. Ad esempio:

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

La descrizione deve specificare qualsiasi valore o comportamento predefinito, ma può omettere la descrizione dei valori predefiniti che sono effettivamente null.

Se il valore del campo è obbligatorio, solo input, solo output, deve 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

La descrizione di un metodo è una frase che indica l'effetto del metodo e su quale risorsa opera. Di solito inizia con una terza persona, verbo presente, ossia in inglese, che termina con "s". Se hai bisogno di aggiungere ulteriori dettagli, utilizza altre frasi. 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 sulla posizione dalla posizione dell'utente autenticato storia.
• Crea o aggiorna un record della posizione nella cronologia della posizione dell'utente autenticato utilizzando i dati inclusi nella richiesta. Se località esiste già con lo stesso valore timestamp, i dati forniti sovrascrivono quelli esistenti.

Elenco di controllo per tutte le descrizioni

Assicurati che ogni descrizione sia breve ma completa e possa essere comprensibile dagli utenti che non hanno informazioni aggiuntive sull'API. Nella maggior parte dei casi, casi, c'è altro da dire che riaffermare l'ovvio: ad esempio la descrizione del metodo series.insert non deve essere limitato "Inserisce una serie." Anche se i nomi devono essere informativi, la maggior parte dei lettori legge le descrizioni perché vuole maggiori informazioni rispetto a quelle fornite dai nomi stessi. Se non sai cosa altro dire in una descrizione, prova a rispondere a tutte le seguenti domande pertinenti:

• Che cos'è?
• Che cosa fa se ha esito positivo? Che cosa fa se non funziona? Cosa può causare un errore e in che modo?
• È idempotente?
• Quali sono le unità? (Esempi: metri, gradi, pixel).
• Quale intervallo di valori accetta? L'intervallo include o esclusivi?
• Quali sono gli effetti collaterali?
• Come lo usi?
• Quali sono gli errori comuni che potrebbero causare un malfunzionamento?
• È sempre presente? Ad esempio: "Container per il voto informazioni. Presente solo quando vengono registrate informazioni sulle votazioni").
• Ha un'impostazione predefinita?

Convenzioni

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

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

Livelli di requisiti

Per impostare aspettative o livelli di requisiti dello stato, utilizza i termini: deve, deve essere not, required, shall, non deve, Where, Dovrebbe non, recommended, may e facoltativo.

I significati sono definiti nel documento RFC 2119. Ti consigliamo di includere l'affermazione dell'abstract dell'RFC nella documentazione dell'API.

Determina quale termine soddisfa i tuoi requisiti fornendo al contempo agli sviluppatori una maggiore flessibilità. Non utilizzare termini assoluti come deve quando altre opzioni funzionano tecnicamente nella tua API.

Stile della lingua

Come per le nostre convenzioni di denominazione, consigliamo di utilizzare un vocabolario e uno stile semplici e coerenti quando scrivi i commenti dei documenti. I commenti devono essere comprensibili per i lettori che non parlano inglese come lingua madre, quindi evita tecnicismi, gergo, metafore complesse, riferimenti alla cultura pop o qualsiasi altro elemento che non possa essere tradotto facilmente. Utilizza un linguaggio professionale e amichevole che parli direttamente agli sviluppatori che leggono i tuoi commenti e mantieni il testo il più conciso possibile. Ricorda: la maggior parte dei lettori vuole sapere come fare qualcosa con l'API, non leggi la documentazione.