Fix incorrect links for operation input / output members in docgen

.changes/next-release/bugfix-68d2165529337bbb64a77fdf4adc1f2fd5685f65.json

@@ -0,0 +1,7 @@
+{
+  "type": "bugfix",
+  "description": "Fix incorrect links for operation input / output members in docgen",
+  "pull_requests": [
+    "[#2922](https://github.com/smithy-lang/smithy/pull/2922)"
+  ]
+}

.changes/smithy_changelog/amend.py

@@ -101,7 +101,7 @@ def amend(
             f'--type feature --description "{description}"\n```\n\n'
             "Make sure that the description is appropriate for a changelog entry and "
             "that the proper feature type is used. See [`./.changes/README`]("
-            f"{GITHUB_URL}/{repository}/tree/main/.changes/README) or run "
+            f"{GITHUB_URL}/{repository}/tree/main/.changes/README.md) or run "
             "`./.changes/new-change -h` for more information."
         )
         post_comment(

smithy-docgen/src/main/java/software/amazon/smithy/docgen/DocSymbolProvider.java

@@ -209,6 +209,9 @@ public Symbol structureShape(StructureShape shape) {
             var operation = ioToOperation.get(shape.getId());
             builder.definitionFile(getDefinitionFile(serviceShape, operation));
             builder.putProperty(OPERATION_PROPERTY, operation);
+            // Input and output structures should use the operation as its link_id
+            String suffix = operation.getInputShape().equals(shape.getId()) ? "-request-members" : "-response-members";
+            builder.putProperty(LINK_ID_PROPERTY, getLinkId(getShapeName(serviceShape, operation)) + suffix);
         }
         return builder.build();
     }
@@ -230,16 +233,22 @@ public Symbol unionShape(UnionShape shape) {
 
     @Override
     public Symbol memberShape(MemberShape shape) {
-        var builder = getSymbolBuilder(shape)
-                .definitionFile(getDefinitionFile(serviceShape, model.expectShape(shape.getId().withoutMember())));
+        var builder = getSymbolBuilder(shape);
 
-        Optional<String> containerLinkId = model.expectShape(shape.getContainer())
+        ShapeId containerId = shape.getContainer();
+        Optional<String> containerLinkId = model.expectShape(containerId)
                 .accept(this)
                 .getProperty(LINK_ID_PROPERTY, String.class);
         if (containerLinkId.isPresent()) {
             var linkId = containerLinkId.get() + "-" + getLinkId(getShapeName(serviceShape, shape));
             builder.putProperty(LINK_ID_PROPERTY, linkId);
         }
+        // Definition file of input / output structure members should be the operation file.
+        if (ioToOperation.containsKey(containerId)) {
+            builder.definitionFile(getDefinitionFile(serviceShape, ioToOperation.get(containerId)));
+        } else {
+            builder.definitionFile(getDefinitionFile(serviceShape, model.expectShape(shape.getId().withoutMember())));
+        }
         return builder.build();
     }
 

smithy-docgen/src/test/java/software/amazon/smithy/docgen/generators/OperationGeneratorTest.java

@@ -142,4 +142,49 @@ public void testGeneratesSnippetsFromDiscoveredConfig(@TempDir Path tempDir) {
                 ```
                 :::"""));
     }
+
+    @Test
+    public void testPaginatedOperation(@TempDir Path tempDir) {
+        MockManifest manifest = new MockManifest();
+        FileManifest sharedManifest = FileManifest.create(tempDir);
+        ObjectNode settings = settings().toBuilder()
+                .withoutMember("snippetConfigs")
+                .build();
+        sharedManifest.writeFile("snippets/snippets.json", IoUtils.readUtf8Url(SNIPPETS_FILE));
+        execute(manifest, sharedManifest, settings);
+        var operationDocs = manifest.expectFileString("/content/operations/PaginatedOperation.md");
+        assertThat(operationDocs,
+                containsString(
+                        """
+                                (paginatedoperation)=
+                                # PaginatedOperation
+
+                                Placeholder documentation for `smithy.example#PaginatedOperation`
+
+                                :::{important}
+                                This operation returns partial results in pages, whose maximum size may be
+                                configured with [pageSize](./PaginatedOperation.md#paginatedoperation-request-members-pagesize). Each request may return an [output token](./PaginatedOperation.md#paginatedoperation-response-members-nexttoken) that may be used as an [input token](./PaginatedOperation.md#paginatedoperation-request-members-nexttoken) in subsequent requests to fetch the next page of results. If the operation does not return an [output token](./PaginatedOperation.md#paginatedoperation-response-members-nexttoken), that means that there are no more results. If the operation returns a repeated [output token](./PaginatedOperation.md#paginatedoperation-response-members-nexttoken), there MAY be more results later.
+                                :::
+
+                                (paginatedoperation-request-members)=
+                                ## Request Members
+
+                                **nextToken (String)**
+                                : Placeholder documentation for `smithy.example#PaginatedOperationInput$nextToken`
+
+                                **pageSize (Integer)**
+                                : Placeholder documentation for `smithy.example#PaginatedOperationInput$pageSize`
+
+
+                                (paginatedoperation-response-members)=
+                                ## Response Members
+
+                                **items (List\\<String\\>)**
+                                : Placeholder documentation for `smithy.example#PaginatedOperationOutput$items`
+
+                                **nextToken (String)**
+                                : Placeholder documentation for `smithy.example#PaginatedOperationOutput$nextToken`
+                                """));
+
+    }
 }

smithy-docgen/src/test/resources/software/amazon/smithy/docgen/generators/operation-generator.smithy

@@ -6,6 +6,7 @@ service TestService {
     operations: [
         NoSnippets
         BasicOperation
+        PaginatedOperation
     ]
 }
 
@@ -83,3 +84,25 @@ operation NoSnippets {
 structure BasicError {
     message: String
 }
+
+@paginated(inputToken: "nextToken", outputToken: "nextToken", pageSize: "pageSize", items: "items")
+operation PaginatedOperation {
+    input: PaginatedOperationInput
+
+    output := {
+        items: Items
+
+        nextToken: String
+    }
+}
+
+@input
+structure PaginatedOperationInput {
+    nextToken: String
+
+    pageSize: Integer
+}
+
+list Items {
+    member: String
+}