Emit JSON path reference in comments for all generated types

Sources/_OpenAPIGeneratorCore/Translator/CommonTypes/CommentExtensions.swift

@@ -96,6 +96,16 @@ extension TypeName {
             suffix: generatedFromCommentText
         )
     }
+
+    func docCommentWithUserDescription(_ userDescription: String?, subPath: String) -> Comment? {
+        guard let fullyQualifiedJSONPath else {
+            return Comment.doc(prefix: userDescription, suffix: nil)
+        }
+        return Comment.doc(
+            prefix: userDescription,
+            suffix:  "- Remark: Generated from `\(fullyQualifiedJSONPath)/\(subPath)`."
+        )
+    }
 }
 
 extension ResponseKind {

Sources/_OpenAPIGeneratorCore/Translator/Content/ContentType.swift

@@ -142,6 +142,10 @@ struct ContentType: Hashable {
     var lowercasedTypeAndSubtype: String {
         "\(lowercasedType)/\(lowercasedSubtype)"
     }
+
+    var lowercasedTypeAndSubtypeWithEscape: String {
+        "\(lowercasedType)\\/\(lowercasedSubtype)"
+    }
 
     /// The header value used when sending a content-type header.
     var headerValueForSending: String {

Sources/_OpenAPIGeneratorCore/Translator/Parameters/translateParameter.swift

@@ -43,7 +43,11 @@ extension TypesFileTranslator {
         } else {
             associatedDeclarations = []
         }
+
+        let comment: Comment? = parent.docCommentWithUserDescription(nil,
+                                                                    subPath: "\(parameter.location.rawValue)/\(parameter.name)")
         return .init(
+            comment: comment,
             isDeprecated: parameter.parameter.deprecated,
             originalName: parameter.name,
             typeUsage: parameter.typeUsage,

Sources/_OpenAPIGeneratorCore/Translator/RequestBody/translateRequestBody.swift

@@ -41,6 +41,7 @@ extension TypesFileTranslator {
     /// - Returns: A list of declarations; empty if the request body is
     /// unsupported.
     func requestBodyContentCases(
+        typeName: TypeName,
         for requestBody: TypedRequestBody
     ) throws -> [Declaration] {
         var bodyMembers: [Declaration] = []
@@ -54,13 +55,20 @@ extension TypesFileTranslator {
             }
             let identifier = contentSwiftName(content.content.contentType)
             let associatedType = content.resolvedTypeUsage
-            let contentCase: Declaration = .enumCase(
-                .init(
+
+            let subPath: String = {
+                let contentPath = typeName.isComponent ? "content" : "requestBody/content"
+                return "\(contentPath)/\(content.content.contentType.lowercasedTypeAndSubtypeWithEscape)"
+            }()
+
+            let contentCase: Declaration = .commentable(
+                typeName.docCommentWithUserDescription(nil, subPath: subPath),
+                .enumCase(.init(
                     name: identifier,
                     kind: .nameWithAssociatedValues([
                         .init(type: associatedType.fullyQualifiedNonOptionalSwiftName)
                     ])
-                )
+                ))
             )
             bodyMembers.append(contentCase)
         }
@@ -131,7 +139,8 @@ extension TypesFileTranslator {
         requestBody: TypedRequestBody
     ) throws -> Declaration {
         let type = requestBody.typeUsage.typeName
-        let members = try requestBodyContentCases(for: requestBody)
+        let members = try requestBodyContentCases(typeName: type,
+                                                  for: requestBody)
         return translateRequestBodyInTypes(
             typeName: type,
             members: members
@@ -154,7 +163,14 @@ extension TypesFileTranslator {
             conformances: Constants.Operation.Output.conformances,
             members: members
         )
-        return bodyEnumDecl
+        let comment: Comment? = {
+            if typeName.isComponent {
+                return typeName.docCommentWithUserDescription(nil)
+            } else {
+                return typeName.docCommentWithUserDescription(nil, subPath: "requestBody")
+            }
+        }()
+        return .commentable(comment, bodyEnumDecl)
     }
 }
 

Sources/_OpenAPIGeneratorCore/Translator/Responses/translateResponse.swift

@@ -20,6 +20,7 @@ extension TypesFileTranslator {
     ///   - typedResponse: The typed response to declare.
     /// - Returns: A structure declaration.
     func translateResponseInTypes(
+        responseKind: String = "",
         typeName: TypeName,
         response: TypedResponse
     ) throws -> Declaration {
@@ -34,10 +35,19 @@ extension TypesFileTranslator {
             inParent: headersTypeName
         )
         let headerProperties: [PropertyBlueprint] = try headers.map { header in
-            try parseResponseHeaderAsProperty(for: header)
+            try parseResponseHeaderAsProperty(
+                responseKind: responseKind,
+                typeName: typeName,
+                for: header)
         }
+        let headerStructComment: Comment? = {
+            let subPath = typeName.isComponent
+                  ? "headers"
+                  : "reponses/\(responseKind)/headers"
+            return typeName.docCommentWithUserDescription(nil, subPath: subPath)
+        }()
         let headersStructBlueprint: StructBlueprint = .init(
-            comment: nil,
+            comment: headerStructComment,
             access: config.access,
             typeName: headersTypeName,
             conformances: Constants.Operation.Output.Payload.Headers.conformances,
@@ -76,22 +86,35 @@ extension TypesFileTranslator {
                 )
                 bodyCases.append(contentsOf: inlineTypeDecls)
             }
-            let bodyCase: Declaration = .enumCase(
-                name: identifier,
-                kind: .nameWithAssociatedValues([
-                    .init(type: associatedType.fullyQualifiedSwiftName)
-                ])
+            let subPathForContentCase = typeName.isComponent
+              ? "content/\(typedContent.content.contentType.lowercasedTypeAndSubtypeWithEscape)"
+              : "reponses/\(responseKind)/content/\(typedContent.content.contentType.lowercasedTypeAndSubtypeWithEscape)"
+            let bodyCase: Declaration = .commentable(
+                typeName.docCommentWithUserDescription(nil, subPath: subPathForContentCase),
+                .enumCase(
+                    name: identifier,
+                    kind: .nameWithAssociatedValues([
+                        .init(type: associatedType.fullyQualifiedSwiftName)
+                    ])
+                )
             )
             bodyCases.append(bodyCase)
         }
+        let subPathForContent = typeName.isComponent
+              ? "content"
+              : "reponses/\(responseKind)/content"
         let hasNoContent: Bool = bodyCases.isEmpty
-        let contentEnumDecl: Declaration = .enum(
-            isFrozen: true,
-            accessModifier: config.access,
-            name: bodyTypeName.shortSwiftName,
-            conformances: Constants.Operation.Body.conformances,
-            members: bodyCases
+        let contentEnumDecl: Declaration = .commentable(
+            typeName.docCommentWithUserDescription(nil, subPath: subPathForContent),
+            .enum(
+                isFrozen: true,
+                accessModifier: config.access,
+                name: bodyTypeName.shortSwiftName,
+                conformances: Constants.Operation.Body.conformances,
+                members: bodyCases
+            )
         )
+
         let contentTypeUsage = bodyTypeName.asUsage.withOptional(hasNoContent)
         let contentProperty = PropertyBlueprint(
             comment: .doc("Received HTTP response body"),

Sources/_OpenAPIGeneratorCore/Translator/Responses/translateResponseHeader.swift

@@ -22,10 +22,18 @@ extension TypesFileTranslator {
     ///   - header: A response parameter.
     /// - Returns: A property blueprint.
     func parseResponseHeaderAsProperty(
+        responseKind: String = "",
+        typeName: TypeName,
         for header: TypedResponseHeader
     ) throws -> PropertyBlueprint {
+        let comment: Comment? = {
+            let subPath: String = typeName.isComponent
+            ? "headers/\(header.name)"
+            : "reponses/\(responseKind)/headers/\(header.name)"
+            return typeName.docCommentWithUserDescription(nil, subPath: subPath)
+        }()
         return .init(
-            comment: nil,
+            comment: comment,
             originalName: header.name,
             typeUsage: header.typeUsage,
             default: header.header.required ? nil : .nil,

Sources/_OpenAPIGeneratorCore/Translator/Responses/translateResponseOutcome.swift

@@ -42,6 +42,7 @@ extension TypesFileTranslator {
         let responseStructDecl: Declaration?
         if typedResponse.isInlined {
             responseStructDecl = try translateResponseInTypes(
+                responseKind: responseKind.jsonPathComponent,
                 typeName: typedResponse.typeUsage.typeName,
                 response: typedResponse
             )

Sources/_OpenAPIGeneratorCore/Translator/TypeAssignment/TypeName.swift

@@ -126,6 +126,10 @@ struct TypeName: Equatable {
         precondition(components.count >= 1, "Cannot get the parent of a root type")
         return .init(components: components.dropLast())
     }
+
+    var isComponent: Bool {
+        description.contains("#/components")
+    }
 }
 
 extension TypeName: CustomStringConvertible {

Sources/_OpenAPIGeneratorCore/Translator/TypesTranslator/translateOperations.swift

@@ -36,13 +36,16 @@ extension TypesFileTranslator {
                     inParent: inputTypeName
                 )
             }
-            let structDecl: Declaration = translateStructBlueprint(
-                .init(
-                    comment: nil,
-                    access: config.access,
-                    typeName: structTypeName,
-                    conformances: Constants.Operation.Input.conformances,
-                    properties: structProperties
+            let structDecl: Declaration = .commentable(
+                inputTypeName.docCommentWithUserDescription(nil, subPath: "\(location.rawValue)"),
+                translateStructBlueprint(
+                    .init(
+                        comment: nil,
+                        access: config.access,
+                        typeName: structTypeName,
+                        conformances: Constants.Operation.Input.conformances,
+                        properties: structProperties
+                    )
                 )
             )