Mettre à jour des SmartDocs

Avant de fournir l'URL de votre portail aux utilisateurs de votre API, vous devez vous assurer que la documentation de référence de l'API SmartDocs est correcte et que l'API se comporte comme indiqué. Lorsque vous passez en revue la documentation de référence générée et le test, il est possible que vous souhaitiez modifier certains éléments.

Cette page décrit :

la documentation de référence de l'API SmartDocs ;
Comment SmartDocs utilise les champs du fichier openapi.json créés par Cloud Endpoints Frameworks pour générer des SmartDocs
comment regénérer des SmartDocs. Le rôle IAM (Cloud Identity and Access Management) minimum requis pour exécuter chaque tâche est indiqué. Pour en savoir plus sur les autorisations IAM, consultez les pages suivantes :

Prérequis

Dans cette page, nous partons du principe que vous avez déjà créé votre portail.

À propos de la documentation de référence de l'API SmartDocs

Lorsque vous ajoutez la gestion d'API comme décrit ci-après :

Endpoints Frameworks crée un document OpenAPI pour votre API. Chaque fois que vous déployez un document OpenAPI sur votre service Endpoints, SmartDocs génère une documentation de référence sur l'API pour votre portail. L'interface utilisateur SmartDocs est basée sur Angular Material, une bibliothèque de composants d'interface utilisateur aux performances optimales. Les développeurs peuvent consulter la documentation de référence SmartDocs de l'API et utiliser le widget Essayer cette API pour interagir avec votre API sans quitter la documentation.

À propos des champs utilisés pour générer des SmartDocs

Lorsque vous ajoutez la gestion d'API comme décrit ci-après :

Endpoints Frameworks crée un document OpenAPI au format JSON pour votre API. Lorsque vous déployez le document OpenAPI en utilisant gcloud endpoints services deploy, SmartDocs génère la documentation de référence de l'API mise à jour pour votre portail basé sur le document OpenAPI créé par Endpoints Frameworks.

Endpoints Frameworks n'inclut pas de descriptions dans le document OpenAPI qu'il crée pour votre API. Avant de fournir l'URL de votre portail aux utilisateurs de l'API, nous vous recommandons d'ajouter des descriptions à l'API, aux méthodes et aux paramètres dans le document OpenAPI.

Si vous débutez avec OpenAPI, commencez par consulter le site Web Swagger Basic Structure (Structure de base Swagger), qui fournit un exemple de document OpenAPI et explique brièvement chaque section du fichier. Pour en savoir plus, consultez la page Spécification OpenAPI.

Comme décrit dans la section Métadonnées, la valeur du champ description peut contenir plusieurs lignes et accepte la spécification GitHub Flavored Markdown.

Pour aider vos utilisateurs à comprendre comment utiliser les méthodes dans votre API, ajoutez un champ description à la section paramètres et au corps de la requête.

Votre document OpenAPI comprend une partie semblable à ce qui suit :

{
 "swagger": "2.0",
 "info": {
  "version": "1.0.0",
  "title": "example-project-12345.appspot.com"
 },
 "host": "example-project-12345.appspot.com",

Les valeurs des champs ci-dessus sont affichées comme suit dans le portail :

title : la valeur du titre est affichée sur la page d'accueil de votre portail dans la section répertoriant les API du projet, sur la page d'accueil de l'API (avec le mot documentation ajouté en complément) et dans la barre de titre de l'API.
host : la valeur de l'hôte (qui est aussi le nom de votre service Cloud Endpoints) est affichée sur la page d'accueil de votre portail dans la section répertoriant les API du projet, ainsi que sur la page Paramètres dans la liste déroulante affichée dans l'onglet API.
version : le numéro de version majeure est utilisé dans l'URL du portail de l'API.

Vous pouvez modifier la valeur du champ title et ajouter un champ description pour l'API. Exemple :

{
 "swagger": "2.0",
 "info": {
  "version": "1.0.0",
  "title": "Endpoints Frameworks Example",
  "description": "A simple Cloud Endpoints Frameworks API example."
 },
 "host": "example-project-12345.appspot.com",

Regénérer des SmartDocs

Autorisations requises pour cette tâche

Pour regénérer les SmartDocs, vous devez déployer votre configuration Endpoints mise à jour. Le rôle Éditeur pour la configuration de service attribué au service dispose des autorisations minimales requises pour redéployer la configuration Endpoints. Pour en savoir plus sur l'attribution de ce rôle, consultez la page Accorder et révoquer l'accès à l'API.

Pour regénérer la documentation de référence, procédez comme suit :

Apportez les modifications au fichier openapi.json généré par Endpoints Frameworks.

Redéployez openapi.json :

gcloud endpoints services deploy openapi.json

Actualisez la page de votre portail.
Enregistrez le fichier openapi.json modifié dans un emplacement où il ne peut pas être remplacé si vous devez par la suite regénérer le fichier openapi.json. Si vous apportez des modifications à votre API et que vous générez de nouveau le fichier openapi.json, vous devez fusionner les modifications dans le fichier openapi.json nouvellement généré avec celles que vous avez effectuées précédemment.

Pour en savoir plus sur cette commande, consultez la page gcloud endpoints services deploy.