Actualizar SmartDocs

OpenAPI   |  gRPC

A partir del 21 de marzo de 2022, el Portal de Cloud Endpoints quedó obsoleto. El Portal de Cloud Endpoints dejará de estar disponible después del 21 de marzo de 2023. El tráfico de API administrado por Cloud Endpoints no se ve afectado por este cambio. Para obtener más información, consulta Bajas de funciones.

Antes de proporcionar la URL del portal a los usuarios de la API, debes asegurarte de que la documentación de referencia de la API de SmartDocs sea correcta y de que la API se comporte según lo esperado. Mientras revisas la documentación de referencia y la prueba que se generaron, es posible que veas algo que deseas cambiar.

En esta página, se describe lo siguiente:

• La documentación de referencia de la API de SmartDocs
• La forma en que SmartDocs usa los campos y comentarios en tus archivos .proto y de configuración de servicio para generar SmartDocs
• Cómo volver a generar SmartDocs

Para cada tarea, se proporcionan las funciones mínimas de Identity and Access Management que se requieren a fin de completarla. Si quieres obtener más información sobre los permisos de IAM, consulta los siguientes recursos:

• Comprende las funciones
• Cómo otorgar, cambiar y revocar el acceso a los recursos
• Crea y administra funciones personalizadas

Requisitos previos

En esta página, se da por sentado que ya creaste tu portal.

Acerca de la documentación de referencia de la API de SmartDocs

Cada vez que implementas una configuración en el servicio de Google Endpoints, SmartDocs genera documentación de referencia de la API para tu portal. La IU de SmartDocs se basa en Angular Material, una biblioteca avanzada de componentes de IU. Los desarrolladores pueden revisar tu documentación de referencia de la API de SmartDocs y usar el widget Prueba esta API para interactuar con tu API sin salir de su documentación.

Acerca de los campos que se utilizan para generar SmartDocs

Tu archivo de configuración de servicio (denominado api_config.yaml) contiene algo similar a lo siguiente:

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

• title: el valor del título se muestra en la página principal de tu portal en la sección que enumera las API del proyecto, en la página principal de la API (con la palabra documentación adjunta) y en la barra de título de la API.

• name: el valor de name (que también es el nombre de tu servicio de Endpoints) se muestra en la página principal de tu portal en la sección que enumera las API del proyecto y en la página Configuración en la lista desplegable de la pestaña API.

El portal de Endpoints genera documentación de referencia para cada método y recurso de RPC en tu archivo .proto. Los comentarios sobre cada método y recurso se incluyen en la documentación que se muestra en tu portal. El siguiente extracto es del archivo .proto que se usó para generar la documentación de referencia en el ejemplo de la API de gRPC de librerías en la Demostración del portal de 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) {}
}

El archivo bookstore.proto completo que se usó en la demostración del portal de Endpoints se encuentra en la muestra bookstore-grpc de Endpoints.

Volver a generar SmartDocs

Permisos requeridos para esta tarea

Para volver a generar SmartDocs, debes implementar tu configuración actualizada de Endpoints. La función de Editor de la configuración del servicio que se otorga en el servicio tiene el mínimo de permisos requeridos para volver a implementar la configuración de Endpoints. Consulta Otorga y revoca el acceso a la API para obtener más información sobre cómo asignar esta función.

Para volver a generar la documentación de referencia:

1. Haz los cambios a tu configuración de servicio o a tus archivos .proto.

2. Si cambiaste el archivo .proto, compila tus búferes de protocolo.

3. Vuelve a implementar tu archivo .pb y el de configuración de servicio, por ejemplo:

   gcloud endpoints services deploy api_descriptor.pb api_config.yaml
   

4. Actualiza la página del portal.

Consulta gcloud endpoints services deploy para obtener más información sobre el comando.