Actualizar SmartDocs

OpenAPI | gRPC

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
Cómo SmartDocs usa los campos de tu documento de OpenAPI para generar SmartDocs
Cómo volver a generar SmartDocs

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

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 un documento de OpenAPI en el servicio de 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 panel Prueba esta API para interactuar con tu API sin salir de la documentación.

Acerca de los campos que se utilizan para generar SmartDocs

Tu documento de OpenAPI contiene información como la siguiente:

swagger: "2.0"
info:
  description: "A simple Google Cloud Endpoints API example."
  title: "Endpoints Example"
  version: "1.0.0"
host: "echo-api.endpoints.example-project-12345.cloud.goog"

Los valores de estos campos se muestran en el portal de la siguiente forma:

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.
description: el valor de la descripción se muestra en una fuente pequeña debajo del título en la página principal de la API.
host: el valor para el host (que también es el nombre de tu servicio de Endpoints) se muestra en la página de inicio de tu portal en la sección que enumera las API del proyecto y en la página Configuración en la lista desplegable que se muestra en la pestaña API.
version: el número de versión principal se usa en la URL del portal de la API.

El portal de Endpoints genera documentación de referencia para cada extremo individual que aparece en la sección paths de tu documento de OpenAPI. Los siguientes extractos son del documento de OpenAPI usado a fin de generar la documentación de referencia para el extremo echo en la “API de ejemplo de Endpoints” en la demostración del portal de Endpoints:

paths:
  "/echo":
    post:
      description: "Echo back a given message."
      operationId: "echo"
      produces:
      - "application/json"
      responses:
        200:
          description: "Echo"
          schema:
            $ref: "#/definitions/echoMessage"
      parameters:
      - description: "Message to echo"
        in: body
        name: message
        required: true
        schema:
          $ref: "#/definitions/echoMessage"
      security:
      - api_key: []

El parámetro para el extremo echo se define en la siguiente sección:

definitions:
  echoMessage:
    type: "object"
    properties:
      message:
        type: "string"

El archivo openapi.yaml completo que se usó en la demostración del portal de Endpoints se encuentra en la muestra getting-started de Endpoints.

Como práctica recomendada, incluye siempre el campo description en las definiciones de propiedad y en todas las demás secciones de tu documento de OpenAPI. El campo description puede contener varias líneas y admite GitHub Flavored Markdown. Lo siguiente, por ejemplo, genera una lista con viñetas en la página principal de la API en un portal:

swagger: "2.0"
info:
  description: "A simple API to help you learn about Cloud Endpoints.

  * item 1

  * item 2"
title: "Endpoints Example"
  version: "1.0.0"
host: "echo-api.endpoints.example-project-12345.cloud.goog"

Cómo 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:

Haz los cambios en tu archivo de OpenAPI.
Vuelve a implementar tu documento de OpenAPI (denominado openapi.yaml en el siguiente comando):
```
gcloud endpoints services deploy openapi.yaml
```
Actualiza la página del portal.

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