public final class Documentation extends GeneratedMessageV3 implements DocumentationOrBuilder
`Documentation` provides the information for describing a service.
Example:
<pre><code>documentation:
summary: >
The Google Calendar API gives access
to most calendar features.
pages:
- name: Overview
content: (== include google/foo/overview.md ==)
- name: Tutorial
content: (== include google/foo/tutorial.md ==)
subpages;
- name: Java
content: (== include google/foo/tutorial_java.md ==)
rules:
- selector: google.calendar.Calendar.Get
description: >
...
- selector: google.calendar.Calendar.Put
description: >
...
</code></pre>
Documentation is provided in markdown syntax. In addition to
standard markdown features, definition lists, tables and fenced
code blocks are supported. Section headers can be provided and are
interpreted relative to the section nesting of the context where
a documentation fragment is embedded.
Documentation from the IDL is merged with documentation defined
via the config at normalization time, where documentation provided
by config rules overrides IDL provided.
A number of constructs specific to the API platform are supported
in documentation text.
In order to reference a proto element, the following
notation can be used:
<pre><code>[fully.qualified.proto.name][]</code></pre>
To override the display text used for the link, this can be used:
<pre><code>[display text][fully.qualified.proto.name]</code></pre>
Text can be excluded from doc using the following notation:
<pre><code>(-- internal comment --)</code></pre>
A few directives are available in documentation. Note that
directives must appear on a single line to be properly
identified. The `include` directive includes a markdown file from
an external source:
<pre><code>(== include path/to/file ==)</code></pre>
The `resource_for` directive marks a message to be the resource of
a collection in REST view. If it is not specified, tools attempt
to infer the resource from the operations in a collection:
<pre><code>(== resource_for v1.shelves.books ==)</code></pre>
The directive `suppress_warning` does not directly affect documentation
and is documented together with service config validation.
Protobuf type google.api.Documentation| Modifier and Type | Class and Description |
|---|---|
static class |
Documentation.Builder
`Documentation` provides the information for describing a service.
|
GeneratedMessageV3.BuilderParent, GeneratedMessageV3.ExtendableBuilder<MessageType extends GeneratedMessageV3.ExtendableMessage,BuilderType extends GeneratedMessageV3.ExtendableBuilder<MessageType,BuilderType>>, GeneratedMessageV3.ExtendableMessage<MessageType extends GeneratedMessageV3.ExtendableMessage>, GeneratedMessageV3.ExtendableMessageOrBuilder<MessageType extends GeneratedMessageV3.ExtendableMessage>, GeneratedMessageV3.FieldAccessorTable| Modifier and Type | Field and Description |
|---|---|
static int |
DOCUMENTATION_ROOT_URL_FIELD_NUMBER |
static int |
OVERVIEW_FIELD_NUMBER |
static int |
PAGES_FIELD_NUMBER |
static int |
RULES_FIELD_NUMBER |
static int |
SUMMARY_FIELD_NUMBER |
alwaysUseFieldBuilders, unknownFieldsmemoizedSizememoizedHashCode| Modifier and Type | Method and Description |
|---|---|
boolean |
equals(java.lang.Object obj) |
static Documentation |
getDefaultInstance() |
Documentation |
getDefaultInstanceForType() |
static Descriptors.Descriptor |
getDescriptor() |
java.lang.String |
getDocumentationRootUrl()
The URL to the root of documentation.
|
ByteString |
getDocumentationRootUrlBytes()
The URL to the root of documentation.
|
java.lang.String |
getOverview()
Declares a single overview page.
|
ByteString |
getOverviewBytes()
Declares a single overview page.
|
Page |
getPages(int index)
The top level pages for the documentation set.
|
int |
getPagesCount()
The top level pages for the documentation set.
|
java.util.List<Page> |
getPagesList()
The top level pages for the documentation set.
|
PageOrBuilder |
getPagesOrBuilder(int index)
The top level pages for the documentation set.
|
java.util.List<? extends PageOrBuilder> |
getPagesOrBuilderList()
The top level pages for the documentation set.
|
Parser<Documentation> |
getParserForType() |
DocumentationRule |
getRules(int index)
A list of documentation rules that apply to individual API elements.
|
int |
getRulesCount()
A list of documentation rules that apply to individual API elements.
|
java.util.List<DocumentationRule> |
getRulesList()
A list of documentation rules that apply to individual API elements.
|
DocumentationRuleOrBuilder |
getRulesOrBuilder(int index)
A list of documentation rules that apply to individual API elements.
|
java.util.List<? extends DocumentationRuleOrBuilder> |
getRulesOrBuilderList()
A list of documentation rules that apply to individual API elements.
|
int |
getSerializedSize() |
java.lang.String |
getSummary()
A short summary of what the service does.
|
ByteString |
getSummaryBytes()
A short summary of what the service does.
|
UnknownFieldSet |
getUnknownFields() |
int |
hashCode() |
protected GeneratedMessageV3.FieldAccessorTable |
internalGetFieldAccessorTable() |
boolean |
isInitialized() |
static Documentation.Builder |
newBuilder() |
static Documentation.Builder |
newBuilder(Documentation prototype) |
Documentation.Builder |
newBuilderForType() |
protected Documentation.Builder |
newBuilderForType(GeneratedMessageV3.BuilderParent parent) |
static Documentation |
parseDelimitedFrom(java.io.InputStream input) |
static Documentation |
parseDelimitedFrom(java.io.InputStream input,
ExtensionRegistryLite extensionRegistry) |
static Documentation |
parseFrom(byte[] data) |
static Documentation |
parseFrom(byte[] data,
ExtensionRegistryLite extensionRegistry) |
static Documentation |
parseFrom(java.nio.ByteBuffer data) |
static Documentation |
parseFrom(java.nio.ByteBuffer data,
ExtensionRegistryLite extensionRegistry) |
static Documentation |
parseFrom(ByteString data) |
static Documentation |
parseFrom(ByteString data,
ExtensionRegistryLite extensionRegistry) |
static Documentation |
parseFrom(CodedInputStream input) |
static Documentation |
parseFrom(CodedInputStream input,
ExtensionRegistryLite extensionRegistry) |
static Documentation |
parseFrom(java.io.InputStream input) |
static Documentation |
parseFrom(java.io.InputStream input,
ExtensionRegistryLite extensionRegistry) |
static Parser<Documentation> |
parser() |
Documentation.Builder |
toBuilder() |
void |
writeTo(CodedOutputStream output) |
canUseUnsafe, computeStringSize, computeStringSizeNoTag, emptyBooleanList, emptyDoubleList, emptyFloatList, emptyIntList, emptyLongList, getAllFields, getDescriptorForType, getField, getOneofFieldDescriptor, getRepeatedField, getRepeatedFieldCount, hasField, hasOneof, internalGetMapField, makeExtensionsImmutable, mutableCopy, mutableCopy, mutableCopy, mutableCopy, mutableCopy, newBooleanList, newBuilderForType, newDoubleList, newFloatList, newIntList, newLongList, parseDelimitedWithIOException, parseDelimitedWithIOException, parseUnknownField, parseUnknownFieldProto3, parseWithIOException, parseWithIOException, parseWithIOException, parseWithIOException, serializeBooleanMapTo, serializeIntegerMapTo, serializeLongMapTo, serializeStringMapTo, writeReplace, writeString, writeStringNoTagfindInitializationErrors, getInitializationErrorString, hashBoolean, hashEnum, hashEnumList, hashFields, hashLong, toStringaddAll, addAll, checkByteStringIsUtf8, toByteArray, toByteString, writeDelimitedTo, writeToclone, finalize, getClass, notify, notifyAll, wait, wait, waitfindInitializationErrors, getAllFields, getDescriptorForType, getField, getInitializationErrorString, getOneofFieldDescriptor, getRepeatedField, getRepeatedFieldCount, hasField, hasOneoftoByteArray, toByteString, writeDelimitedTo, writeTopublic static final int SUMMARY_FIELD_NUMBER
public static final int PAGES_FIELD_NUMBER
public static final int RULES_FIELD_NUMBER
public static final int DOCUMENTATION_ROOT_URL_FIELD_NUMBER
public static final int OVERVIEW_FIELD_NUMBER
public final UnknownFieldSet getUnknownFields()
getUnknownFields in interface MessageOrBuildergetUnknownFields in class GeneratedMessageV3public static final Descriptors.Descriptor getDescriptor()
protected GeneratedMessageV3.FieldAccessorTable internalGetFieldAccessorTable()
internalGetFieldAccessorTable in class GeneratedMessageV3public java.lang.String getSummary()
A short summary of what the service does. Can only be provided by plain text.
string summary = 1;getSummary in interface DocumentationOrBuilderpublic ByteString getSummaryBytes()
A short summary of what the service does. Can only be provided by plain text.
string summary = 1;getSummaryBytes in interface DocumentationOrBuilderpublic java.util.List<Page> getPagesList()
The top level pages for the documentation set.
repeated .google.api.Page pages = 5;getPagesList in interface DocumentationOrBuilderpublic java.util.List<? extends PageOrBuilder> getPagesOrBuilderList()
The top level pages for the documentation set.
repeated .google.api.Page pages = 5;getPagesOrBuilderList in interface DocumentationOrBuilderpublic int getPagesCount()
The top level pages for the documentation set.
repeated .google.api.Page pages = 5;getPagesCount in interface DocumentationOrBuilderpublic Page getPages(int index)
The top level pages for the documentation set.
repeated .google.api.Page pages = 5;getPages in interface DocumentationOrBuilderpublic PageOrBuilder getPagesOrBuilder(int index)
The top level pages for the documentation set.
repeated .google.api.Page pages = 5;getPagesOrBuilder in interface DocumentationOrBuilderpublic java.util.List<DocumentationRule> getRulesList()
A list of documentation rules that apply to individual API elements. **NOTE:** All service configuration rules follow "last one wins" order.
repeated .google.api.DocumentationRule rules = 3;getRulesList in interface DocumentationOrBuilderpublic java.util.List<? extends DocumentationRuleOrBuilder> getRulesOrBuilderList()
A list of documentation rules that apply to individual API elements. **NOTE:** All service configuration rules follow "last one wins" order.
repeated .google.api.DocumentationRule rules = 3;getRulesOrBuilderList in interface DocumentationOrBuilderpublic int getRulesCount()
A list of documentation rules that apply to individual API elements. **NOTE:** All service configuration rules follow "last one wins" order.
repeated .google.api.DocumentationRule rules = 3;getRulesCount in interface DocumentationOrBuilderpublic DocumentationRule getRules(int index)
A list of documentation rules that apply to individual API elements. **NOTE:** All service configuration rules follow "last one wins" order.
repeated .google.api.DocumentationRule rules = 3;getRules in interface DocumentationOrBuilderpublic DocumentationRuleOrBuilder getRulesOrBuilder(int index)
A list of documentation rules that apply to individual API elements. **NOTE:** All service configuration rules follow "last one wins" order.
repeated .google.api.DocumentationRule rules = 3;getRulesOrBuilder in interface DocumentationOrBuilderpublic java.lang.String getDocumentationRootUrl()
The URL to the root of documentation.
string documentation_root_url = 4;getDocumentationRootUrl in interface DocumentationOrBuilderpublic ByteString getDocumentationRootUrlBytes()
The URL to the root of documentation.
string documentation_root_url = 4;getDocumentationRootUrlBytes in interface DocumentationOrBuilderpublic java.lang.String getOverview()
Declares a single overview page. For example:
<pre><code>documentation:
summary: ...
overview: (== include overview.md ==)
</code></pre>
This is a shortcut for the following declaration (using pages style):
<pre><code>documentation:
summary: ...
pages:
- name: Overview
content: (== include overview.md ==)
</code></pre>
Note: you cannot specify both `overview` field and `pages` field.
string overview = 2;getOverview in interface DocumentationOrBuilderpublic ByteString getOverviewBytes()
Declares a single overview page. For example:
<pre><code>documentation:
summary: ...
overview: (== include overview.md ==)
</code></pre>
This is a shortcut for the following declaration (using pages style):
<pre><code>documentation:
summary: ...
pages:
- name: Overview
content: (== include overview.md ==)
</code></pre>
Note: you cannot specify both `overview` field and `pages` field.
string overview = 2;getOverviewBytes in interface DocumentationOrBuilderpublic final boolean isInitialized()
isInitialized in interface MessageLiteOrBuilderisInitialized in class GeneratedMessageV3public void writeTo(CodedOutputStream output) throws java.io.IOException
writeTo in interface MessageLitewriteTo in class GeneratedMessageV3java.io.IOExceptionpublic int getSerializedSize()
getSerializedSize in interface MessageLitegetSerializedSize in class GeneratedMessageV3public boolean equals(java.lang.Object obj)
equals in interface Messageequals in class AbstractMessagepublic int hashCode()
hashCode in interface MessagehashCode in class AbstractMessagepublic static Documentation parseFrom(java.nio.ByteBuffer data) throws InvalidProtocolBufferException
InvalidProtocolBufferExceptionpublic static Documentation parseFrom(java.nio.ByteBuffer data, ExtensionRegistryLite extensionRegistry) throws InvalidProtocolBufferException
InvalidProtocolBufferExceptionpublic static Documentation parseFrom(ByteString data) throws InvalidProtocolBufferException
InvalidProtocolBufferExceptionpublic static Documentation parseFrom(ByteString data, ExtensionRegistryLite extensionRegistry) throws InvalidProtocolBufferException
InvalidProtocolBufferExceptionpublic static Documentation parseFrom(byte[] data) throws InvalidProtocolBufferException
InvalidProtocolBufferExceptionpublic static Documentation parseFrom(byte[] data, ExtensionRegistryLite extensionRegistry) throws InvalidProtocolBufferException
InvalidProtocolBufferExceptionpublic static Documentation parseFrom(java.io.InputStream input) throws java.io.IOException
java.io.IOExceptionpublic static Documentation parseFrom(java.io.InputStream input, ExtensionRegistryLite extensionRegistry) throws java.io.IOException
java.io.IOExceptionpublic static Documentation parseDelimitedFrom(java.io.InputStream input) throws java.io.IOException
java.io.IOExceptionpublic static Documentation parseDelimitedFrom(java.io.InputStream input, ExtensionRegistryLite extensionRegistry) throws java.io.IOException
java.io.IOExceptionpublic static Documentation parseFrom(CodedInputStream input) throws java.io.IOException
java.io.IOExceptionpublic static Documentation parseFrom(CodedInputStream input, ExtensionRegistryLite extensionRegistry) throws java.io.IOException
java.io.IOExceptionpublic Documentation.Builder newBuilderForType()
newBuilderForType in interface MessagenewBuilderForType in interface MessageLitepublic static Documentation.Builder newBuilder()
public static Documentation.Builder newBuilder(Documentation prototype)
public Documentation.Builder toBuilder()
toBuilder in interface MessagetoBuilder in interface MessageLiteprotected Documentation.Builder newBuilderForType(GeneratedMessageV3.BuilderParent parent)
newBuilderForType in class GeneratedMessageV3public static Documentation getDefaultInstance()
public static Parser<Documentation> parser()
public Parser<Documentation> getParserForType()
getParserForType in interface MessagegetParserForType in interface MessageLitegetParserForType in class GeneratedMessageV3public Documentation getDefaultInstanceForType()
getDefaultInstanceForType in interface MessageLiteOrBuildergetDefaultInstanceForType in interface MessageOrBuilder