Documentación

En esta sección se proporcionan pautas para agregar documentación en línea a tu API. La mayoría de las API también tendrán descripciones generales, instructivos y documentación de referencia de nivel superior, que están fuera del alcance de esta Guía de diseño. Para obtener información sobre la API, los recursos y la denominación de métodos, consulta las Convenciones de nomenclatura.

Formato de comentario

Agrega comentarios a tu archivo .proto con el formato de comentarios normal de los búferes de protocolo de dos barras consecutivas (//).

// Creates a shelf in the library, and returns the new Shelf.
rpc CreateShelf(CreateShelfRequest) returns (Shelf) {
  option (google.api.http) = { post: "/v1/shelves" body: "shelf" };
}

Comentarios en la configuración del servicio

Como alternativa a agregar comentarios de documentación a tu archivo .proto, puedes agregar documentación en línea a tu API en tu archivo de configuración de servicio YAML. La documentación en este archivo tendrá prioridad sobre la documentación en tu .proto si el mismo elemento está documentado en ambos archivos.

documentation:
  summary: Gets and lists social activities
  overview: A simple example service that lets you get and list possible social activities
  rules:
  - selector: google.social.Social.GetActivity
    description: Gets a social activity. If the activity does not exist, returns Code.NOT_FOUND.
...

Es posible que debas utilizar este enfoque si tienes varios servicios que usan los mismos archivos .proto y deseas proporcionar documentación específica del servicio. Las reglas de documentación de YAML también te permiten agregar una overview más detallada a la descripción de tu API. Sin embargo, en general se prefiere agregar comentarios de documentación a tu .proto.

Al igual que con los comentarios .proto, puedes usar Markdown para proporcionar un formato adicional en los comentarios de tu archivo YAML.

Descripción de la API

La descripción de la API es una frase que comienza con un verbo activo que describe lo que puedes hacer con la API. En tu archivo .proto, se agrega una descripción de la API como un comentario al service correspondiente, como en el siguiente ejemplo:

// Manages books and shelves in a simple digital library.
service LibraryService {
...
}

Aquí hay algunos ejemplos más de descripciones de API:

  • Shares updates, photos, videos, and more with your friends around the world (Comparte actualizaciones, fotos, videos y más con tus amigos en todo el mundo).
  • Accesses a cloud-hosted machine learning service that makes it easy to build smart apps that respond to streams of data (Accede a un servicio de aprendizaje automático en la nube que facilita el diseño de apps inteligentes que reaccionan a los flujos de datos).

Descripción del recurso

Una descripción de recurso es una oración parcial que describe lo que representa el recurso. Si necesitas agregar más detalles, usa oraciones adicionales. En tu archivo .proto, se agrega una descripción de recurso como un comentario al tipo de mensaje correspondiente, como en el siguiente ejemplo:

// A book resource in the Library API.
message Book {
  ...
}

Aquí hay algunas descripciones de recursos de ejemplo:

  • A task on the user's to-do list. Each task has a unique priority (Una tarea en la lista de tareas pendientes del usuario. Cada tarea tiene una prioridad única).
  • An event on the user's calendar (Un evento en el calendario del usuario).

Descripciones de campos y parámetros

Una frase nominal que describe una definición de campo o parámetro, como se muestra en los siguientes ejemplos:

  • The number of topics in this series (El número de temas en esta serie).
  • The accuracy of the latitude and longitude coordinates, in meters. Must be non-negative (La precisión de las coordenadas de latitud y longitud, en metros. No debe ser un valor negativo).
  • Flag governing whether attachment URL values are returned for submission resources in this series. The default value for series.insert is true (Marca que indica si los valores de URL de los adjuntos se devuelven a los recursos de envío en esta serie. El valor predeterminado de series.insert es verdadero).
  • The container for voting information. Present only when voting information is recorded (El contenedor para la información de votación, incluido solo cuando se registra esta información).
  • Not currently used or deprecated (No se usa actualmente o es obsoleto).

Descripciones de campos y parámetros

  • Debes describir los límites con claridad (es decir, tener claro qué es válido y qué no lo es. Recuerda que los ingenieros harán todo lo posible por interrumpir cualquier servicio y no podrán leer el código subyacente para aclarar cualquier información que no esté clara.
  • Debes especificar cualquier valor predeterminado o comportamiento predeterminado; en otras palabras, qué hará el servidor si no se proporciona ningún valor.
  • Si se trata de una string, como un nombre o una ruta, describe la sintaxis y la lista de caracteres permitidos, y cualquier codificación requerida. Por ejemplo:
    • 1-255 caracteres en el conjunto [A-a0-9]
    • Una string de ruta de URL válida que comienza con / que sigue las convenciones de RFC 2332. La longitud máxima es de 500 caracteres.
  • Debes proporcionar un valor de ejemplo siempre que sea posible.
  • Si el valor del campo es obligatorio, solo entrada, solo salida, debe documentarse al comienzo de la descripción del campo. De forma predeterminada, todos los campos y parámetros son opcionales. Por ejemplo:
message Table {
  // Required. The resource name of the table.
  string name = 1;
  // Input only. Whether to dry run the table creation.
  bool dryrun = 2;
  // Output only. The timestamp when the table was created. Assigned by
  // the server.
  Timestamp create_time = 3;
  // The display name of the table.
  string display_name = 4;
}

Descripción del método

Una descripción del método es una oración que indica qué efecto tiene el método y en qué recurso opera. Por lo general, comienza con un verbo en la tercera persona del presente, es decir, un verbo que termina en “s” en inglés. Si necesitas agregar más detalles, usa oraciones adicionales. A continuación, se incluyen algunos ejemplos:

  • Lists calendar events for the authenticated user (Enumera eventos de calendario para el usuario autenticado).
  • Updates a calendar event with the data included in the request (Actualiza un evento de calendario con los datos incluidos en la solicitud).
  • Deletes a location record from the authenticated user's location history (Borra un registro de ubicación del historial de ubicaciones del usuario autenticado).
  • Creates or updates a location record in the authenticated user's location history using the data included in the request. If a location resource already exists with the same timestamp value, the data provided overwrites the existing data (Crea o actualiza un registro de ubicación en el historial de ubicación con los datos incluidos en la solicitud. Si un recurso de ubicación ya existe con la misma marca de tiempo, los datos proporcionados sobreescriben a los datos existentes).

Lista de tareas para todas las descripciones

Asegúrate de que cada descripción sea breve, pero completa, y que los usuarios que no cuentan con información adicional sobre la API puedan comprenderla. En la mayoría de los casos, puedes hacer más que reafirmar lo obvio; por ejemplo, la descripción del método series.insert no debería solo decir “Inserta una serie”. Aunque tu nomenclatura debe ser informativa, la mayoría de los lectores leen tus descripciones porque quieren más información que la que proporcionan los nombres. Si no estás seguro de qué más decir en una descripción, intenta responder las siguientes preguntas relevantes:

  • ¿De qué se trata?
  • ¿Qué hace si tiene éxito? ¿Qué hace si falla? ¿Qué puede hacer que falle y cómo?
  • ¿Es idempotente?
  • ¿Cuáles son las unidades? (Ejemplos: metros, grados, píxeles).
  • ¿Qué rango de valores acepta? ¿El rango es inclusivo o exclusivo?
  • ¿Cuáles son los efectos secundarios?
  • ¿Cómo lo usas?
  • ¿Cuáles son los errores comunes que pueden romperlo?
  • ¿Está siempre presente? (Por ejemplo: “Contenedor para información de votación. Presente solo cuando se registra la información de la votación”).
  • ¿Tiene una configuración predeterminada?

Convenciones

En esta sección, se enumeran algunas convenciones de uso para descripciones textuales y documentación. Por ejemplo, usa “ID” (todo en mayúsculas), en lugar de “Id” o “id” cuando se habla de identificadores. Usa “JSON” en lugar de “Json” o “json” cuando te refieras a ese formato de datos. Muestra todos los nombres de campo/parámetro en code font. Pon valores de literal de string en code font y comillas.

  • ID
  • JSON
  • RPC
  • REST
  • property_name o "string_literal"
  • true / false

Niveles de exigencia

Para establecer las expectativas o niveles de exigencia de estado, usa los términos: must (debes), must not (no debes), required (obligatorio), shall (debería), shall not (no debería), should (debe), should not (no debe), recommended (recomendado), may (puede) y optional (opcional).

Los significados se definen en RFC 2119. Es posible que desees incluir la declaración del resumen de RFC en la documentación de la API.

Determina qué término cumple con tus requisitos y ofrece flexibilidad a los desarrolladores. No uses términos absolutos como must (debe) cuando otras opciones técnicamente funcionan en tu API.

Estilo de lenguaje

Al igual que en nuestras convenciones de nomenclatura, recomendamos usar un vocabulario y estilo simples y coherentes cuando se escriben comentarios sobre documentos. Los comentarios deben ser comprensibles para los lectores que no hablan inglés de forma nativa, así que evita el argot, la jerga, las metáforas complejas, las referencias a la cultura pop o cualquier otra cosa que no se traduzca con facilidad. Usa un estilo amigable y profesional que hable directamente a los desarrolladores que leen tus comentarios y mantén todo tan conciso como sea posible. Recuerda, la mayoría de los lectores quieren saber cómo hacer algo con tu API, no leer tu documentación.

¿Te ha resultado útil esta página? Enviar comentarios:

Enviar comentarios sobre...