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.
- 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 dename
(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
Pour regénérer la documentation de référence, procédez comme suit :
Apportez les modifications voulues à votre fichier de configuration de service et/ou à votre fichier
.proto
.Si vous avez modifié votre fichier
.proto
, compilez vos tampons de protocole.Redéployez votre fichier
.pb
et votre fichier de configuration de service. Par exemple :gcloud endpoints services deploy api_descriptor.pb api_config.yaml
Actualisez la page de votre portail.
Pour en savoir plus sur cette commande, consultez la page gcloud endpoints services deploy
.