Support externalDocs when converting operations to OpenAPI

smithy-openapi/src/main/java/software/amazon/smithy/openapi/fromsmithy/OpenApiConverter.java

@@ -449,6 +449,10 @@ private <T extends Trait> void addPaths(
                         .map(DocumentationTrait::getValue)
                         .ifPresent(description -> result.getOperation().description(description));
 
+                // The externalDocumentation trait of the operation maps to externalDocs.
+                OpenApiJsonSchemaMapper.getResolvedExternalDocs(shape, context.getConfig())
+                        .ifPresent(result.getOperation()::externalDocs);
+
                 OperationObject builtOperation = result.getOperation().build();
 
                 // Pass the operation through the plugin system.

smithy-openapi/src/test/java/software/amazon/smithy/openapi/fromsmithy/OpenApiConverterTest.java

@@ -523,6 +523,22 @@ public void convertsDocumentation() {
         Node.assertEquals(result, expectedNode);
     }
 
+    @Test
+    public void convertsExternalDocumentation() {
+        Model model = Model.assembler()
+                .addImport(getClass().getResource("externaldocs-test.smithy"))
+                .discoverModels()
+                .assemble()
+                .unwrap();
+        OpenApiConfig config = new OpenApiConfig();
+        config.setService(ShapeId.from("smithy.example#MyDocs"));
+        Node result = OpenApiConverter.create().config(config).convertToNode(model);
+        Node expectedNode = Node.parse(IoUtils.toUtf8String(
+                getClass().getResourceAsStream("externaldocs-test.openapi.json")));
+
+        Node.assertEquals(result, expectedNode);
+    }
+
     @Test
     public void properlyDealsWithServiceRenames() {
         Model model = Model.assembler()

smithy-openapi/src/test/resources/software/amazon/smithy/openapi/fromsmithy/externaldocs-test.openapi.json

@@ -0,0 +1,50 @@
+{
+  "openapi": "3.0.2",
+  "info": {
+    "title": "MyDocs",
+    "version": "2018-01-01"
+  },
+  "externalDocumentation": {
+    "description": "API Reference",
+    "url": "https://localhost/docs/service"
+  },
+  "paths": {
+    "/": {
+      "get": {
+        "externalDocs": {
+          "description": "API Reference",
+          "url": "https://localhost/docs/operation"
+        },
+        "operationId": "MyDocsOperation",
+        "responses": {
+          "200": {
+            "description": "MyDocsOperation 200 response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/MyDocsOperationResponseContent"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "MyDocsOperationResponseContent": {
+        "type": "object",
+        "properties": {
+          "foo": {
+            "type": "string"
+          }
+        },
+        "externalDocs": {
+          "description": "API Reference",
+          "url": "https://localhost/docs/output"
+        }
+      }
+    }
+  }
+}

smithy-openapi/src/test/resources/software/amazon/smithy/openapi/fromsmithy/externaldocs-test.smithy

@@ -0,0 +1,28 @@
+$version: "2.0"
+
+namespace smithy.example
+
+@externalDocumentation(
+    "API Reference": "https://localhost/docs/service"
+)
+@aws.protocols#restJson1
+service MyDocs {
+    version: "2018-01-01",
+    operations: [MyDocsOperation]
+}
+
+@externalDocumentation(
+    "API Reference": "https://localhost/docs/operation"
+)
+@http(method: "GET", uri: "/")
+@readonly
+operation MyDocsOperation {
+    output: Output
+}
+
+@externalDocumentation(
+    "API Reference": "https://localhost/docs/output"
+)
+structure Output {
+    foo: String
+}