Agrega documentación personalizada

Además de la documentación de referencia de la API de SmartDocs, puedes agregar documentación personalizada a tu portal, que los usuarios de tu API pueden necesitar. Incluso si no necesitas ofrecer a tus usuarios páginas de documentación adicionales, deberás actualizar la guía de introducción de ejemplo que se muestra en tu portal para explicar cómo comenzar a usar tu API.

Esta página describe cómo cambiar la guía de introducción de ejemplo, y cómo crear y mostrar las páginas de documentación adicionales para tu portal. 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:

Requisitos previos

En esta página se supone que:

Acerca de la documentación personalizada

Para mostrar la documentación personalizada en tu portal, debes almacenar los archivos en un repositorio de Git y configurar la URL que lleva al repositorio de Git en la página de Configuración de tu portal. Puedes agregar los archivos de tu documentación personalizada a:

  • Un repositorio privado ubicado en Cloud Source Repositories que se encuentra en el mismo proyecto de Google Cloud que tu API
  • Un repositorio público en GitHub o Bitbucket

Los archivos y carpetas que se encuentran en tu repositorio deben tener una estructura específica para que el Portal de Cloud Endpoints encuentre y muestre tu documentación personalizada. En la raíz del repositorio, debes tener una carpeta con tu nombre de servicio de Cloud Endpoints. Puedes crear subcarpetas adicionales según sea necesario. La barra de navegación izquierda contiene vínculos a tus carpetas y archivos. Para obtener más información, consulta la Estructura de directorio obligatoria.

Usa Markdown para editar el contenido en la guía de introducción y para escribir el contenido de páginas de documentación adicionales. El Portal de Endpoints sigue la especificación de CommonMark, así como la extensión de tabla de la especificación de GitHub Flavored Markdown.

También puedes agregar imágenes a tu repositorio y hacer referencia a ellas desde tus archivos de Markdown.

Comenzar a actualizar de la documentación personalizada

Para ayudarte a comenzar, te recomendamos que clones el repositorio endpoints-developer-portal-sample-content en GitHub que contiene los siguientes archivos:

  • Getting Started.md, el archivo de Markdown que tiene el contenido de la página de introducción de ejemplo que se muestra en tu portal.
  • Example Page.md: un archivo de ejemplo para ayudarte a comenzar a usar Markdown.
  • navigation.yaml: un archivo que describe el orden de las páginas y carpetas en la barra de navegación izquierda en tu portal.
  • add_example_page, una secuencia de comandos que hace lo siguiente:

    • Crea un repositorio de Git en Cloud Source Repositories, en tu proyecto de Google Cloud.
    • Crea un repositorio de Git local en la carpeta default-content-repo.
    • Crea una carpeta con el mismo nombre que tu servicio de Endpoints y una subcarpeta llamada Guides.
    • Agrega archivos llamados Example Page.md y Getting Started.md a la carpeta Guides.
    • Agrega Example Page al archivo navigation.yaml.
    • Confirma y envía estos cambios al repositorio de Git recién creado en Cloud Source Repositories.

    Hay dos versiones de la secuencia de comandos:

    • Para usuarios de Linux y Mac, existe add_example_page.sh (Bash shell).
    • Para los usuarios de Windows, existe add_example_page.ps1 (PowerShell).

    Ejecutar la secuencia de comandos es opcional. Si lo prefieres, puedes crear de forma manual un repositorio en Cloud Source Repositories o en un repositorio público en GitHub o Bitbucket. Debes configurar la estructura de directorio obligatoria para tu documentación personalizada.

    Antes de ejecutar la secuencia de comandos, es posible que desees revisar la documentación de Precios y cuota para Cloud Source Repositories. Si ejecutas la secuencia de comandos y, luego, decides que prefieres usar un repositorio público de GitHub o Bitbucket, puedes borrar el repositorio de Cloud Source Repositories.

Obtén los archivos de inicio de la documentación personalizada

En esta sección, se describe cómo realizar la configuración para que puedas ejecutar la secuencia de comandos add_example_page.

Para obtener los archivos de inicio de la documentación personalizada, haz lo siguiente:

  1. Habilita la API de Cloud Source Repositories:

    1. En API y servicios, ve a la página de Biblioteca de la API.

      Ir a la biblioteca de la API

    2. En la lista de proyectos, selecciona el proyecto en el que se encuentra tu API.

    3. Busca la API de Cloud Source Repositories y haz clic en su tarjeta para visualizar su página de información.

    4. Haz clic en Habilitar.

  2. Asegúrate de que la CLI de gcloud esté autorizada para acceder a tus datos y servicios:

    gcloud auth login
    
  3. Configura el proyecto predeterminado. En el siguiente comando, reemplaza YOUR_PROJECT_ID con el ID del proyecto de Google Cloud en el que creaste la API de Endpoints:

    gcloud config set project YOUR_PROJECT_ID
    
  4. Descarga el contenido de muestra, la configuración y las secuencias de comandos:

    git clone https://github.com/GoogleCloudPlatform/endpoints-developer-portal-sample-content
    
  5. Cambia al directorio que contiene la secuencia de comandos:

    cd endpoints-developer-portal-sample-content/scripts
    
  6. Muestra el nombre de tu servicio de Endpoints:

    gcloud endpoints services list
    
  7. Ejecuta la secuencia de comandos con tu nombre de servicio de Endpoints:

    • Usuarios de Linux y Mac: ./add_example_page.sh SERVICE_NAME
    • Usuarios de Windows: add_example_page.ps1 SERVICE_NAME

    Cuando finalice la secuencia de comandos, imprime las URL en las siguientes ubicaciones:

    • Tu configuración del portal de la API

    • Tu URL de Git. Esta es la misma URL que se muestra en el campo Clonar URL en la página Cloud Source Repositories

  8. Sincroniza el repositorio con el portal:

    1. Destaca y copia la primera URL; luego, pégala en la barra de direcciones de tu navegador para ir a la página Configuración.
    2. Sigue los mensajes de acceso para ir a la página Configuración de tu API. Si tienes más de una cuenta, asegúrate de elegir la cuenta que está en el proyecto de Google Cloud que posee la API.
    3. Destaca y copia la URL de clonación para el repositorio de Git y, luego, pégala en el campo Configuración de contenido personalizado.
    4. Haz clic en Sincronizar.
    5. Haz clic en Guardar.
    6. Para volver a la página de destino de la documentación de la API, haz clic en la barra de título.

    En la barra de navegación izquierda, haz clic en la Página de ejemplo para visualizar el contenido.

  9. Explora el contenido del repositorio que creaste recientemente. En la consola de Google Cloud, ve a la página Repositorios fuente > Código fuente del proyecto.

    Ir al Navegador de código fuente

    El navegador de código fuente muestra una vista del directorio de los contenidos del repositorio en el nivel de confirmación más reciente. Consulta Explorar repositorios para obtener más información.

Modificar la documentación personalizada

Ahora que tienes documentación personalizada en Cloud Source Repositories, puedes modificar el contenido y agregar o borrar archivos y carpetas según sea necesario. Si recién comienzas a usar Git, la documentación de Git contiene documentación de referencia y vínculos a libros y videos.

Modifica el contenido de Getting Started

Para modificar el contenido de Getting Started, haz lo siguiente:

  1. Desde la raíz del repositorio de Git local, ve a la carpeta que tiene el mismo nombre que tu servicio de Endpoints. Por ejemplo:

    cd example-api.example.com
    
  2. Ve a la carpeta que contiene Getting Started.md:

    cd Guides
    
  3. Abre Getting Started.md en un editor de texto.

  4. Modifica el contenido según sea necesario para ayudar a tus usuarios a comenzar a usar tu API.

  5. Guarda el archivo.

  6. Confirma tus cambios:

    git commit -a -m "updated getting started"
    
  7. Envía tus cambios a tu repositorio en Cloud Source Repositories:

    git push
    
  8. Sincroniza el contenido actualizado en tu portal:

    1. Ve a tu portal.
    2. Haz clic en Configuración.
    3. En la página Configuración, haz clic en la pestaña API y selecciona tu API de la lista.
    4. Haz clic en Sincronizar.
    5. Haz clic en Guardar.

    Cuando haces clic en el vínculo Introducción en la barra de navegación izquierda, el Portal de Endpoints muestra el contenido actualizado.

Quita Example Page

Para quitar Example Page, haz lo siguiente:

  1. Desde la raíz del repositorio de Git local, ve a la carpeta que tiene el mismo nombre que tu servicio de Endpoints. Por ejemplo:

    cd example-api.example.com
    
  2. Abre el archivo navigation.yaml en un editor de texto.

  3. En la sección ordering, borra la línea con Example Page.

  4. Guarda el archivo.

  5. Quita el archivo Example Page.md de Git:

    git rm ‘Guides/Example Page.md'
    
  6. Confirma tus cambios:

    git commit -a -m "removed example page"
    
  7. Envía tus cambios a tu repositorio en Cloud Source Repositories:

    git push
    
  8. Sincroniza el contenido actualizado en tu portal:

    1. Ve a tu portal.
    2. Haz clic en Configuración.
    3. En la página Configuración, haz clic en la pestaña API y selecciona tu API de la lista.
    4. Haz clic en Sincronizar.
    5. Haz clic en Guardar.

Example Page ya no está en la barra de navegación izquierda.

Cambiar el nombre de Example Page

Para cambiar el nombre de Example Page, haz lo siguiente:

  1. Desde la raíz del repositorio de Git local, ve a la carpeta que tiene el mismo nombre que tu servicio de Endpoints. Por ejemplo:

    cd example-api.example.com
    
  2. Abre el archivo navigation.yaml en un editor de texto.

  3. En la sección ordering, cambia el texto Página de ejemplo por el título de tu guía. El nombre debe coincidir con el nombre del archivo real en el directorio Guides.

  4. Guarda el archivo.

  5. Cambia el nombre del archivo Example Page.md en Git.

    git mv 'Guides/Example Page.md' 'Guides/NEW FILENAME.md'
  6. Modifica el contenido del archivo al que le cambiaste el nombre según sea necesario.

  7. Confirma tus cambios:

    git commit -a -m "removed example page"
    
  8. Envía tus cambios a tu repositorio en Cloud Source Repositories:

    git push
    
  9. Sincroniza el contenido actualizado en tu portal:

    1. Ve a tu portal.
    2. Haz clic en Configuración.
    3. En la página Configuración, haz clic en la pestaña API y selecciona tu API de la lista.
    4. Haz clic en Sincronizar.
    5. Haz clic en Guardar.

Se muestra la página a la que le cambiaste el nombre en la barra de navegación izquierda.

Estructura de directorio obligatoria

Los archivos y carpetas que se encuentran en tu repositorio deben tener una estructura específica para que el Portal de Endpoints encuentre y muestre tu contenido personalizado.

En la raíz del repositorio, debe haber una carpeta con tu nombre de servicio de Endpoints. Esta estructura te brinda la opción de utilizar un repositorio para varias API, pues tiene carpetas de nivel de raíz separadas para cada API.

Las subcarpetas dentro de tu carpeta de servicio te permiten agrupar las páginas relacionadas en una sección y pueden contener otras subcarpetas. El título de las carpetas y los nombres de los archivos se usan en la navegación. Por ejemplo, un archivo llamado Getting Started.md aparece en la barra de navegación izquierda como Getting Started. Dentro de la carpeta que recibe su nombre según tu nombre de servicio de Endpoints, debes tener un archivo llamado navigation.yaml. Este archivo indica cómo quieres que aparezca tu contenido en la barra de navegación izquierda en tu portal. El predeterminado tiene el siguiente aspecto:

ordering:
- Introduction
- Guides
- API Reference
- Resources

folders:
  Guides:
    ordering:
    - Getting Started
    - Example Page

La primera lista de ordering especifica el orden en el que quieres que aparezcan las entradas en ese nivel. Por ejemplo, el archivo predeterminado navigation.yaml especifica que la página Introduction aparece primero, seguida de la sección Guides, y así de forma sucesiva.

Introduction, API Reference y Resources son secciones especiales, y no debes quitarlas de navigation.yaml, pero puedes cambiar su orden.

Cada carpeta y página debe tener una configuración correspondiente dentro de la configuración folders de su superior en navigation.yaml. Si se omite, la página o carpeta no aparecerá en tu portal. Por ejemplo, en el archivo predeterminado navigation.yaml, la clave folders contiene una subclave llamada Guides porque hay una carpeta con el mismo nombre.

Agregar imágenes

Puedes agregar imágenes al repositorio de Git de contenido personalizado y hacer referencia a ellas en tus archivos de Markdown. Si colocas las imágenes y cualquier archivo de Markdown que haga referencia a ellas en el mismo directorio que tu nombre de servicio de Endpoints, puedes hacer referencia a las imágenes con una URL relativa (que comience con una /).

Por ejemplo, supón que tienes la estructura de directorio siguiente:

~/example-api.example.com/
    get-started.md
    images/
        example.jpg

Puedes agregar la imagen images/example.jpg a get-started.md con el lenguaje de marcado siguiente:

    ![alt-text](/images/example.jpg "Optional title")

Puedes agregar imágenes alojadas en otro lugar con la sintaxis de Markdown estándar y la URL completa a la imagen:

    ![alt-text](https://example.com/image.png "Optional title")

El portal admite los siguientes tipos de imágenes:

  • BMP
  • GIF
  • JPEG
  • PNG
  • TIFF
  • WEBP

Límites de contenido personalizado

El portal tiene las siguientes limitaciones de contenido personalizado:

  • Un máximo de 200 páginas de Markdown por API.
  • Un máximo de 200 imágenes por API.
  • Un tamaño máximo de 4 MiB por imagen

¿Qué sigue?