From d6934381320a6af4ce7ee917841c4711b1d7f9b5 Mon Sep 17 00:00:00 2001
From: Thomas Farr <tsfarr@amazon.com>
Date: Thu, 11 May 2023 12:14:52 +1200
Subject: [PATCH] Support `externalDocs` when converting operations to OpenAPI

---
 .../openapi/fromsmithy/OpenApiConverter.java  |  4 ++
 .../fromsmithy/OpenApiConverterTest.java      | 16 ++++++
 .../fromsmithy/externaldocs-test.openapi.json | 50 +++++++++++++++++++
 .../fromsmithy/externaldocs-test.smithy       | 28 +++++++++++
 4 files changed, 98 insertions(+)
 create mode 100644 smithy-openapi/src/test/resources/software/amazon/smithy/openapi/fromsmithy/externaldocs-test.openapi.json
 create mode 100644 smithy-openapi/src/test/resources/software/amazon/smithy/openapi/fromsmithy/externaldocs-test.smithy

diff --git a/smithy-openapi/src/main/java/software/amazon/smithy/openapi/fromsmithy/OpenApiConverter.java b/smithy-openapi/src/main/java/software/amazon/smithy/openapi/fromsmithy/OpenApiConverter.java
index 60571d13574..4424a0480db 100644
--- a/smithy-openapi/src/main/java/software/amazon/smithy/openapi/fromsmithy/OpenApiConverter.java
+++ b/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.
diff --git a/smithy-openapi/src/test/java/software/amazon/smithy/openapi/fromsmithy/OpenApiConverterTest.java b/smithy-openapi/src/test/java/software/amazon/smithy/openapi/fromsmithy/OpenApiConverterTest.java
index fb7944d73d6..7c519fbc5ba 100644
--- a/smithy-openapi/src/test/java/software/amazon/smithy/openapi/fromsmithy/OpenApiConverterTest.java
+++ b/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()
diff --git a/smithy-openapi/src/test/resources/software/amazon/smithy/openapi/fromsmithy/externaldocs-test.openapi.json b/smithy-openapi/src/test/resources/software/amazon/smithy/openapi/fromsmithy/externaldocs-test.openapi.json
new file mode 100644
index 00000000000..9d365fce98f
--- /dev/null
+++ b/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"
+        }
+      }
+    }
+  }
+}
\ No newline at end of file
diff --git a/smithy-openapi/src/test/resources/software/amazon/smithy/openapi/fromsmithy/externaldocs-test.smithy b/smithy-openapi/src/test/resources/software/amazon/smithy/openapi/fromsmithy/externaldocs-test.smithy
new file mode 100644
index 00000000000..c6717b90ba4
--- /dev/null
+++ b/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
+}
\ No newline at end of file