Documentation intégrée sur les API

Cette section fournit des consignes pour ajouter une documentation intégrée à votre API. La plupart des API proposent également des présentations, des tutoriels et une documentation de référence de niveau supérieur, qui n'entrent pas dans le champ d'application de ce guide de conception. Pour plus d'informations sur l'attribution de noms des API, des ressources et des méthodes, consultez la section Conventions d'attribution de noms.

Format des commentaires dans les fichiers proto

Ajoutez des commentaires à votre fichier .proto en utilisant le format de commentaire habituel // de 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" };
}

Commentaires dans la configuration de service

Au lieu d'ajouter des commentaires de documentation à votre fichier .proto, vous pouvez ajouter une documentation intégrée à votre API dans son fichier de configuration de service YAML. La documentation de ce fichier aura la priorité sur la documentation de votre fichier .proto si le même élément est documenté dans les deux fichiers.

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.
...

Vous devrez peut-être utiliser cette approche si vous avez plusieurs services qui utilisent les mêmes fichiers .proto et que vous souhaitez fournir une documentation spécifique au service. Les règles de documentation YAML vous permettent également d'ajouter un élément overview plus détaillé à la description de votre API. Toutefois, il est préférable d'ajouter des commentaires sur la documentation dans votre fichier .proto.

Comme pour les commentaires .proto, vous pouvez utiliser Markdown pour fournir une mise en forme supplémentaire des commentaires dans votre fichier YAML.

Description de l'API

La description de l'API est une phrase commençant par un verbe d'action qui décrit ce que l'API vous permet de faire. Dans votre fichier .proto, une description de l'API est ajoutée en tant que commentaire au service correspondant, comme dans l'exemple suivant :

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

Voici d'autres exemples de descriptions d'API :

• Partage des mises à jour, des photos, des vidéos et plus encore avec vos amis du monde entier.
• Accède à un service de machine learning hébergé sur le cloud, facilitant la création d'applications intelligentes afin de répondre aux flux de données.

Description de la ressource

Une description de ressource est une phrase partielle décrivant ce que représente la ressource. Si vous devez ajouter plus de détails, utilisez des phrases supplémentaires. Dans votre fichier .proto, une description de la ressource est ajoutée en tant que commentaire au type de message correspondant, comme dans l'exemple suivant :

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

Voici quelques exemples de descriptions de ressources :

• Une tâche dans la liste de tâches de l'utilisateur. Chaque tâche a une priorité unique.
• Un événement sur le calendrier de l'utilisateur.

Descriptions du champ et des paramètres

Il s'agit d'une phrase nominale qui décrit une définition de champ ou de paramètre, comme illustré dans les exemples suivants :

• Le nombre de thèmes de cette série
• La précision des coordonnées de latitude et de longitude, en mètres. Cette valeur ne doit pas être négative
• Indicateur déterminant si les valeurs URL des pièces jointes sont renvoyées pour les ressources envoyées dans cette série. La valeur par défaut de series.insert est true.
• Le conteneur des informations de vote. Présent uniquement lorsque les informations de vote sont enregistrées
• Non utilisé actuellement ou obsolète

Les descriptions de champs et de paramètres devraient décrire quelles valeurs sont valides et non valides. N'oubliez pas que les ingénieurs font de leur mieux pour interrompre tout service et ne sont pas en mesure de lire le code sous-jacent pour clarifier les informations qui prêtent à confusion.

Pour les chaînes, la description devrait décrire la syntaxe, les caractères autorisés et tout codage requis. Exemple :

• 1 à 255 caractères de l'ensemble [A-a0-9]
• Un chemin d'URL valide sous forme de chaîne commençant par / et conforme aux conventions du protocole RFC 2332. La longueur maximale est de 500 caractères.

La description devrait spécifier tout comportement ou valeur par défaut, mais peut omettre les valeurs par défaut qui sont effectivement nulles.

Si la valeur du champ est requise, uniquement en entrée, uniquement en sortie, elle devrait être documentée au début de la description du champ. Par défaut, tous les champs et paramètres sont facultatifs. Exemple :

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;
}

Remarque :Les descriptions des champs devraient fournir un exemple de valeur chaque fois que cela est possible et utile.

Description de la méthode

Une description de la méthode est une phrase indiquant quel est son effet et la ressource sur laquelle elle agit. Elle commence généralement par un verbe au présent, à la troisième personne. Si vous devez ajouter plus de détails, utilisez des phrases supplémentaires. Voici quelques exemples :

• Répertorie les événements de calendrier pour l'utilisateur authentifié.
• Met à jour un événement de calendrier avec les données incluses dans la requête.
• Supprime un enregistrement de position de l'historique des positions de l'utilisateur authentifié.
• Crée ou met à jour un enregistrement de position dans l'historique des positions de l'utilisateur authentifié à l'aide des données incluses dans la requête. Si une ressource d'emplacement existe déjà avec la même valeur d'horodatage, les données fournies écrasent les données existantes.

Liste de contrôle pour toutes les descriptions

Assurez-vous que chaque description est brève, mais complète et qu'elle peut être comprise par les utilisateurs qui ne disposent pas d'informations supplémentaires sur l'API. Dans la plupart des cas, il y a beaucoup plus de choses à dire que de répéter simplement des évidences. Par exemple, la description de la méthode series.insert ne doit pas se contenter de dire "Insère une série". Bien que les noms attribués doivent être informatifs, la plupart des lecteurs lisent vos descriptions, car ils veulent plus d'informations que celles livrées par les noms. Si vous ne savez pas quoi mettre dans une description, essayez de répondre à toutes les questions pertinentes parmi les suivantes :

• De quoi s'agit-il ?
• Que se passe-t-il si elle aboutit ? Que se passe-t-il en cas d'échec ? Qu'est-ce qui peut la faire échouer et comment ?
• Est-elle idempotente ?
• Quelles sont les unités ? (Exemples : mètres, degrés, pixels.)
• Quelle plage de valeurs accepte-t-elle ? La plage est-elle inclusive ou exclusive ?
• Quels sont les effets secondaires ?
• Comment l'utilisez-vous ?
• Quelles sont les erreurs courantes qui peuvent l'interrompre ?
• Est-elle toujours présente ? (Par exemple : "Conteneur pour les informations de vote. Présente seulement si les informations de vote sont enregistrées.")
• A-t-elle un paramètre par défaut ?

Conventions

Cette section répertorie certaines conventions d'utilisation pour les descriptions textuelles et la documentation. Par exemple, utilisez "ID" (en majuscules) plutôt que "Id" ou "id" lorsque vous parlez d'identifiants. Utilisez "JSON" plutôt que "Json" ou "json" lorsque vous vous référez à ce format de données. Citez tous les noms de champs/paramètres dans code font. Utilisez des valeurs de chaîne littérales et des guillemets dans code font.

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

Niveaux d'exigence

Pour définir les attentes ou les niveaux d'exigence de l'état, utilisez les termes suivants : doit, ne doit pas, exige, devra, ne devra pas, devrait, ne devrait pas, recommandé, peut et facultatif.

Les significations sont définies dans le protocole RFC 2119. Vous voudrez peut-être inclure l'instruction du résumé RFC dans la documentation de votre API.

Déterminez le terme qui répond à vos besoins tout en laissant de la flexibilité aux développeurs. N'utilisez pas de termes absolus comme doit lorsque d'autres options fonctionnent techniquement dans votre API.

Style linguistique

Comme dans nos conventions d'attribution de noms, nous recommandons d'utiliser un vocabulaire et un style simples et cohérents lors de la rédaction de commentaires dans la documentation. Les lecteurs d'une autre langue maternelle doivent pouvoir comprendre les commentaires, évitez donc le jargon, l'argot, les métaphores complexes, les références à la culture pop ou tout autre élément qui ne serait pas facile à traduire. Utilisez un style amical et professionnel qui parle directement aux développeurs qui lisent vos commentaires, et soyez le plus concis possible. N'oubliez pas que la plupart des lecteurs veulent savoir comment utiliser votre API sans lire votre documentation !