Add pagination information

Author: JordonPhillips

smithy-docgen-core/src/main/java/software/amazon/smithy/docgen/core/integrations/BuiltinsIntegration.java

@@ -20,6 +20,7 @@
 import software.amazon.smithy.docgen.core.interceptors.NoReplaceBindingInterceptor;
 import software.amazon.smithy.docgen.core.interceptors.NoReplaceOperationInterceptor;
 import software.amazon.smithy.docgen.core.interceptors.NullabilityInterceptor;
+import software.amazon.smithy.docgen.core.interceptors.PaginationInterceptor;
 import software.amazon.smithy.docgen.core.interceptors.PatternInterceptor;
 import software.amazon.smithy.docgen.core.interceptors.RangeInterceptor;
 import software.amazon.smithy.docgen.core.interceptors.RecommendedInterceptor;
@@ -70,6 +71,7 @@ public List<? extends CodeInterceptor<? extends CodeSection, DocWriter>> interce
         // the ones at the end will be at the top of the rendered pages. Therefore, interceptors
         // that provide more critical information should appear at the bottom of this list.
         return List.of(
+                new PaginationInterceptor(),
                 new RequestCompressionInterceptor(),
                 new NoReplaceBindingInterceptor(),
                 new NoReplaceOperationInterceptor(),

smithy-docgen-core/src/main/java/software/amazon/smithy/docgen/core/interceptors/PaginationInterceptor.java

@@ -0,0 +1,60 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package software.amazon.smithy.docgen.core.interceptors;
+
+import software.amazon.smithy.codegen.core.SymbolReference;
+import software.amazon.smithy.docgen.core.sections.ShapeDetailsSection;
+import software.amazon.smithy.docgen.core.writers.DocWriter;
+import software.amazon.smithy.docgen.core.writers.DocWriter.AdmonitionType;
+import software.amazon.smithy.model.knowledge.PaginatedIndex;
+import software.amazon.smithy.model.traits.PaginatedTrait;
+import software.amazon.smithy.utils.CodeInterceptor;
+
+/**
+ * This adds pagination information to operation docs.
+ */
+public final class PaginationInterceptor implements CodeInterceptor<ShapeDetailsSection, DocWriter> {
+    @Override
+    public Class<ShapeDetailsSection> sectionType() {
+        return ShapeDetailsSection.class;
+    }
+
+    @Override
+    public boolean isIntercepted(ShapeDetailsSection section) {
+        return section.shape().isOperationShape() && section.shape().hasTrait(PaginatedTrait.class);
+    }
+
+    @Override
+    public void write(DocWriter writer, String previousText, ShapeDetailsSection section) {
+        var paginatedIndex = PaginatedIndex.of(section.context().model());
+        var service = section.context().settings().service();
+        var paginationInfo = paginatedIndex.getPaginationInfo(service, section.shape()).get();
+        var symbolProvider = section.context().symbolProvider();
+        writer.putContext("size", paginationInfo.getPageSizeMember().map(symbolProvider::toSymbol));
+        writer.putContext("inputToken", SymbolReference.builder()
+                .symbol(symbolProvider.toSymbol(paginationInfo.getInputTokenMember()))
+                .alias("input token")
+                .build());
+
+        var outputTokenPath = paginationInfo.getOutputTokenMemberPath();
+        var outputToken = outputTokenPath.get(outputTokenPath.size() - 1);
+        writer.putContext("outputToken", SymbolReference.builder()
+                .symbol(symbolProvider.toSymbol(outputToken))
+                .alias("output token")
+                .build());
+
+        writer.openAdmonition(AdmonitionType.IMPORTANT);
+        writer.write("""
+                This operation returns partial results in pages${?size}, whose maximum size may be
+                configured with ${size:R}${/size}. Each request may return an ${outputToken:R} that \
+                may be used as an ${inputToken:R} in subsequent requests to fetch the next page of results. \
+                If the operation does not return an ${outputToken:R}, that means that there are \
+                no more results. If the operation returns a repeated ${outputToken:R}, there MAY be \
+                more results later.""");
+        writer.closeAdmonition();
+        writer.writeWithNoFormatting(previousText);
+    }
+}

smithy-docgen-test/model/main.smithy

@@ -344,16 +344,22 @@ operation DeleteArchivedDocumentation {}
 
 /// Lists the avialable documentation resources.
 @readonly
+@paginated(inputToken: "paginationToken", outputToken: "paginationToken", items: "documentation", pageSize: "pageSize")
 operation ListDocumentation {
     input := {
         // Whether to list documentation that has been archived.
         showArchived: Boolean = false
+
+        paginationToken: String
+
+        pageSize: Integer
     }
 
     output := {
-        /// A list of all the documentation. No pagination here.
         @required
         documentation: DocumentationList
+
+        paginationToken: String
     }
 }