Mettre à jour des SmartDocs

OpenAPI | gRPC

Depuis le 21 mars 2022, le portail Cloud Endpoints est obsolète. Le portail Cloud Endpoints ne sera plus disponible après le 21 mars 2023. Le trafic des API géré par Cloud Endpoints n'est pas affecté par cette modification. Pour en savoir plus, consultez la page Abandons de fonctionnalités.

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 et les commentaires de votre fichier .proto et du fichier de configuration du service pour générer des SmartDocs ;
• comment régénérer les SmartDocs.

Pour chaque tâche, le ou les rôles Identity and Access Management minimaux requis pour l'exécution sont fournis. Pour en savoir plus sur les autorisations IAM, consultez les pages suivantes :

• Comprendre les rôles
• Accorder, modifier et révoquer les accès à des ressources
• Créer et gérer les rôles personnalisés

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

Chaque fois que vous déployez une configuration de service sur votre service Endpoints, SmartDocs génère une documentation de référence relative à 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

Votre fichier de configuration de service (appelé api_config.yaml) se présente comme suit :

title: Bookstore gRPC API
apis:
- name: endpoints.examples.bookstore.Bookstore

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

• name : la valeur de name (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.

Le portail Endpoints génère une documentation de référence pour chaque méthode et ressource RPC de votre fichier .proto. Les commentaires associés à chaque méthode et ressource sont inclus dans la documentation affichée sur votre portail. L'extrait suivant provient du fichier .proto utilisé pour générer la documentation de référence de l'exemple d'API gRPC Bookstore présenté dans la démonstration du portail Endpoints :

service Bookstore {
  // Returns a list of all shelves in the bookstore.
  rpc ListShelves(google.protobuf.Empty) returns (ListShelvesResponse) {}
  // Creates a new shelf in the bookstore.
  rpc CreateShelf(CreateShelfRequest) returns (Shelf) {}
  // Returns a specific bookstore shelf.
  rpc GetShelf(GetShelfRequest) returns (Shelf) {}
  // Deletes a shelf, including all books that are stored on the shelf.
  rpc DeleteShelf(DeleteShelfRequest) returns (google.protobuf.Empty) {}
  // Returns a list of books on a shelf.
  rpc ListBooks(ListBooksRequest) returns (ListBooksResponse) {}
  // Creates a new book.
  rpc CreateBook(CreateBookRequest) returns (Book) {}
  // Returns a specific book.
  rpc GetBook(GetBookRequest) returns (Book) {}
  // Deletes a book from a shelf.
  rpc DeleteBook(DeleteBookRequest) returns (google.protobuf.Empty) {}
}

Le fichier bookstore.proto complet utilisé dans la démonstration du portail Endpoints se trouve dans l'exemple Endpoints bookstore-grpc.

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 :

1. Apportez les modifications voulues à votre fichier de configuration de service et/ou à votre fichier .proto.

2. Si vous avez modifié votre fichier .proto, compilez vos tampons de protocole.

3. Redéployez votre fichier .pb et votre fichier de configuration de service. Par exemple :

   gcloud endpoints services deploy api_descriptor.pb api_config.yaml
   

4. Actualisez la page de votre portail.

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