Inline API documentation

This section provides guidelines for adding inline documentation to your API. Most APIs will also have overviews, tutorials, and higher-level reference documentation, which are outside the scope of this Design Guide. For information on API, resource, and method naming, see Naming Conventions.

Comment format in proto files

Add comments to your .proto file using the usual Protocol Buffers // comment format.

// 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" };
}

Comments in service configuration

As an alternative to adding documentation comments to your .proto file, you can add inline documentation to your API in its YAML service configuration file. Documentation in this file will take precedence over documentation in your .proto if the same element is documented in both files.

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.
...

You may need to use this approach if you have multiple services that use the same .proto files and want to provide service-specific documentation. YAML documentation rules also let you add a more detailed overview to your API description. However, in general adding documentation comments to your .proto is preferred.

As with .proto comments, you can use Markdown to provide additional formatting in your YAML file comments.

API description

The API description is a phrase starting with an active verb that describes what you can do with the API. In your .proto file, an API description is added as a comment to the corresponding service, as in the following example:

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

Here are some more example API descriptions:

  • Shares updates, photos, videos, and more with your friends around the world.
  • Accesses a cloud-hosted machine learning service that makes it easy to build smart apps that respond to streams of data.

Resource description

A resource description is a partial sentence that describes what the resource represents. If you need to add more detail, use additional sentences. In your .proto file, a resource description is added as a comment to the corresponding message type, as in the following example:

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

Here are some example resource descriptions:

  • A task on the user's to-do list. Each task has a unique priority.
  • An event on the user's calendar.

Field and parameter descriptions

A noun phrase that describes a field or parameter definition, as shown in the following examples:

  • The number of topics in this series.
  • The accuracy of the latitude and longitude coordinates, in meters. Must be non-negative.
  • Flag governing whether attachment URL values are returned for submission resources in this series. The default value for series.insert is true.
  • The container for voting information. Present only when voting information is recorded.
  • Not currently used or deprecated.

Field and parameter descriptions should describe what values are valid and invalid. Remember that engineers will do their best to break any service, and will not be able to read the underlying code to clarify any unclear information.

For strings, the description should describe the syntax and permissible characters, as well as any required encoding. For example:

  • 1-255 characters in the set [A-a0-9]
  • A valid URL path string starting with / that follows the RFC 2332 conventions. Max length is 500 characters.

The description should specify any default value or behavior, but may omit describing default values that are effectively null.

If the field value is required, input only, output only, it should be documented at the start of the field description. By default, all fields and parameters are optional. For example:

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;
}

Method description

A method description is a sentence indicating what effect the method has and what resource it operates on. It usually starts with a third-person, present tense verb, i.e., in English, a verb ending in "s". If you need to add more details, use additional sentences. Here are some examples:

  • Lists calendar events for the authenticated user.
  • Updates a calendar event with the data included in the request.
  • Deletes a location record from the authenticated user's location history.
  • 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.

Checklist for all descriptions

Make sure each description is brief but complete and can be understood by users who don't have additional information about the API. In most cases, there's more to say than just restating the obvious; for example, the description of the series.insert method shouldn't just say "Inserts a series." — while your naming should be informative, most readers are reading your descriptions because they want more information than the names themselves provide. If you're not sure what else to say in a description, try answering all of the following questions that are relevant:

  • What is it?
  • What does it do if it succeeds? What does it do if it fails? What can cause it to fail, and how?
  • Is it idempotent?
  • What are the units? (Examples: meters, degrees, pixels.)
  • What range of values does it accept? Is the range inclusive or exclusive?
  • What are the side effects?
  • How do you use it?
  • What are common errors that may break it?
  • Is it always present? (For example: "Container for voting information. Present only when voting information is recorded.")
  • Does it have a default setting?

Conventions

This section lists some usage conventions for textual descriptions and documentation. For example, use "ID" (all caps), rather than "Id" or "id" when talking about identifiers. Use "JSON" rather than "Json" or "json" when referring to that data format. Show all field/parameter names in code font. Put literal string values in code font and quotes.

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

Requirement levels

To set expectations or state requirement levels, use the terms: must, must not, required, shall, shall not, should, should not, recommended, may, and optional.

The meanings are defined in RFC 2119. You might want to include the statement from the RFC abstract in your API documentation.

Determine which term meets your requirements while giving developers flexibility. Don't use absolute terms like must when other options technically work in your API.

Language style

As in our naming conventions, we recommend using a simple, consistent vocabulary and style when writing doc comments. Comments should be understandable by readers who don't speak English natively, so avoid jargon, slang, complex metaphors, pop culture references, or anything else that won't easily translate. Use a friendly, professional style that speaks directly to the developers reading your comments, and keep things as concise as possible. Remember, most readers want to find out how to do something with your API, not read your documentation!