Documentación de la API de Inline

En esta sección se proporcionan pautas para agregar documentación intercalada 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 comentarios en archivos proto

Agrega comentarios a tu archivo .proto con el formato de comentarios normal // de los búferes de protocolo.

// 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 su archivo .proto, puede agregar documentación intercalada a su API en su archivo de configuración del 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. El valor predeterminado para series.insert es true.
• 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).

Las descripciones de campos y parámetros deben describir qué valores son válidos y no válidos. Recuerda que los ingenieros harán todo lo posible para dañar cualquier servicio y no podrán leer el código subyacente para aclarar cualquier información poco clara.

Para las strings, la descripción debería describir la sintaxis y los caracteres permitidos, así como cualquier codificación necesaria. 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.

La descripción debería especificar cualquier valor o comportamiento predeterminado, pero podría describir los valores predeterminados que son nulos de manera efectiva.

Si el valor del campo es obligatorio, solo entrada, solo salida, debería documentarse en el inicio 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 validate table creation without actually doing it.
  bool validate_only = 2;

  // Output only. The timestamp when the table was created. Assigned by
  // the server.
  google.protobuf.Timestamp create_time = 3;

  // The display name of the table.
  string display_name = 4;
}

Nota: Las descripciones de los campos deben proporcionar un valor de ejemplo siempre que sea factible y útil.

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. Estos son 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).
• Crea o actualiza un registro de ubicación en el historial de ubicaciones del usuario autenticado con los datos incluidos en la solicitud. Si ya existe un recurso de ubicación con el mismo valor de marca de tiempo, los datos proporcionados reemplazan los existentes.

Lista de tareas para todas las descripciones

Asegúrate de que cada descripción sea breve, pero de que esté completa y que los usuarios que no tengan información adicional sobre la API puedan comprenderla. En la mayoría de los casos, hay más para decir que simplemente aclarar lo obvio. Por ejemplo, la descripción del método series.insert no debe decir solo “Inserta una serie”. Si bien tu nombre debe ser informativo, la mayoría de los lectores leen tus descripciones, ya que 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. Ponga valores de string literales 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.