From 3ffeaba0c83b4513bfd6c8844480cd3fbff5a10a Mon Sep 17 00:00:00 2001 From: takeshi-1000 Date: Sun, 20 Aug 2023 19:03:11 +0900 Subject: [PATCH] All descriptions defined in the OpenAPI document are generated (#213) --- .../CommonTypes/CommentExtensions.swift | 2 +- .../Responses/translateResponseHeader.swift | 2 +- .../Resources/Docs/petstore.yaml | 3 ++ .../ReferenceSources/Petstore/Types.swift | 46 ++++++++++++++----- .../Types.swift | 46 ++++++++++++++----- 5 files changed, 75 insertions(+), 24 deletions(-) diff --git a/Sources/_OpenAPIGeneratorCore/Translator/CommonTypes/CommentExtensions.swift b/Sources/_OpenAPIGeneratorCore/Translator/CommonTypes/CommentExtensions.swift index b35829a2..b12be738 100644 --- a/Sources/_OpenAPIGeneratorCore/Translator/CommonTypes/CommentExtensions.swift +++ b/Sources/_OpenAPIGeneratorCore/Translator/CommonTypes/CommentExtensions.swift @@ -154,7 +154,7 @@ extension TypedParameter { /// - parent: The parent type of the parameter. func docComment(parent: TypeName) -> Comment? { parent.docCommentWithUserDescription( - nil, + parameter.description, subPath: "\(parameter.location.rawValue)/\(parameter.name)" ) } diff --git a/Sources/_OpenAPIGeneratorCore/Translator/Responses/translateResponseHeader.swift b/Sources/_OpenAPIGeneratorCore/Translator/Responses/translateResponseHeader.swift index f8a79bae..867b9885 100644 --- a/Sources/_OpenAPIGeneratorCore/Translator/Responses/translateResponseHeader.swift +++ b/Sources/_OpenAPIGeneratorCore/Translator/Responses/translateResponseHeader.swift @@ -27,7 +27,7 @@ extension TypesFileTranslator { parent: TypeName ) throws -> PropertyBlueprint { let comment = parent.docCommentWithUserDescription( - nil, + header.header.description, subPath: header.name ) return .init( diff --git a/Tests/OpenAPIGeneratorReferenceTests/Resources/Docs/petstore.yaml b/Tests/OpenAPIGeneratorReferenceTests/Resources/Docs/petstore.yaml index 70658d85..b1bd44d1 100644 --- a/Tests/OpenAPIGeneratorReferenceTests/Resources/Docs/petstore.yaml +++ b/Tests/OpenAPIGeneratorReferenceTests/Resources/Docs/petstore.yaml @@ -210,6 +210,7 @@ paths: components: headers: TracingHeader: + description: A description here. required: false schema: type: string @@ -426,6 +427,7 @@ components: description: Bad request headers: X-Reason: + description: A description here. schema: type: string content: @@ -446,6 +448,7 @@ components: type: object properties: name: + description: "Pet name" type: string kind: $ref: '#/components/schemas/PetKind' diff --git a/Tests/OpenAPIGeneratorReferenceTests/Resources/ReferenceSources/Petstore/Types.swift b/Tests/OpenAPIGeneratorReferenceTests/Resources/ReferenceSources/Petstore/Types.swift index 81ef17f8..ae063876 100644 --- a/Tests/OpenAPIGeneratorReferenceTests/Resources/ReferenceSources/Petstore/Types.swift +++ b/Tests/OpenAPIGeneratorReferenceTests/Resources/ReferenceSources/Petstore/Types.swift @@ -640,6 +640,8 @@ public enum Components { @frozen public enum UpdatePetRequest: Sendable, Equatable, Hashable { /// - Remark: Generated from `#/components/requestBodies/UpdatePetRequest/json`. public struct jsonPayload: Codable, Equatable, Hashable, Sendable { + /// Pet name + /// /// - Remark: Generated from `#/components/requestBodies/UpdatePetRequest/json/name`. public var name: Swift.String? /// - Remark: Generated from `#/components/requestBodies/UpdatePetRequest/json/kind`. @@ -649,7 +651,7 @@ public enum Components { /// Creates a new `jsonPayload`. /// /// - Parameters: - /// - name: + /// - name: Pet name /// - kind: /// - tag: public init( @@ -676,12 +678,14 @@ public enum Components { public struct ErrorBadRequest: Sendable, Equatable, Hashable { /// - Remark: Generated from `#/components/responses/ErrorBadRequest/headers`. public struct Headers: Sendable, Equatable, Hashable { + /// A description here. + /// /// - Remark: Generated from `#/components/responses/ErrorBadRequest/headers/X-Reason`. public var X_Reason: Swift.String? /// Creates a new `Headers`. /// /// - Parameters: - /// - X_Reason: + /// - X_Reason: A description here. public init(X_Reason: Swift.String? = nil) { self.X_Reason = X_Reason } } /// Received HTTP response headers @@ -720,6 +724,8 @@ public enum Components { } /// Types generated from the `#/components/headers` section of the OpenAPI document. public enum Headers { + /// A description here. + /// /// - Remark: Generated from `#/components/headers/TracingHeader`. public typealias TracingHeader = Swift.String } @@ -744,6 +750,8 @@ public enum Operations { public var path: Operations.listPets.Input.Path /// - Remark: Generated from `#/paths/pets/GET/query`. public struct Query: Sendable, Equatable, Hashable { + /// How many items to return at one time (max 100) + /// /// - Remark: Generated from `#/paths/pets/GET/query/limit`. public var limit: Swift.Int32? /// - Remark: Generated from `#/paths/pets/GET/query/habitat`. @@ -814,15 +822,17 @@ public enum Operations { .feedsPayloadPayload] /// - Remark: Generated from `#/paths/pets/GET/query/feeds`. public var feeds: Operations.listPets.Input.Query.feedsPayload? + /// Supply this parameter to filter pets born since the provided date. + /// /// - Remark: Generated from `#/paths/pets/GET/query/since`. public var since: Components.Parameters.query_born_since? /// Creates a new `Query`. /// /// - Parameters: - /// - limit: + /// - limit: How many items to return at one time (max 100) /// - habitat: /// - feeds: - /// - since: + /// - since: Supply this parameter to filter pets born since the provided date. public init( limit: Swift.Int32? = nil, habitat: Operations.listPets.Input.Query.habitatPayload? = nil, @@ -838,12 +848,14 @@ public enum Operations { public var query: Operations.listPets.Input.Query /// - Remark: Generated from `#/paths/pets/GET/header`. public struct Headers: Sendable, Equatable, Hashable { + /// Request identifier + /// /// - Remark: Generated from `#/paths/pets/GET/header/My-Request-UUID`. public var My_Request_UUID: Swift.String? /// Creates a new `Headers`. /// /// - Parameters: - /// - My_Request_UUID: + /// - My_Request_UUID: Request identifier public init(My_Request_UUID: Swift.String? = nil) { self.My_Request_UUID = My_Request_UUID } @@ -884,15 +896,19 @@ public enum Operations { public struct Ok: Sendable, Equatable, Hashable { /// - Remark: Generated from `#/paths/pets/GET/responses/200/headers`. public struct Headers: Sendable, Equatable, Hashable { + /// Response identifier + /// /// - Remark: Generated from `#/paths/pets/GET/responses/200/headers/My-Response-UUID`. public var My_Response_UUID: Swift.String + /// A description here. + /// /// - Remark: Generated from `#/paths/pets/GET/responses/200/headers/My-Tracing-Header`. public var My_Tracing_Header: Components.Headers.TracingHeader? /// Creates a new `Headers`. /// /// - Parameters: - /// - My_Response_UUID: - /// - My_Tracing_Header: + /// - My_Response_UUID: Response identifier + /// - My_Tracing_Header: A description here. public init( My_Response_UUID: Swift.String, My_Tracing_Header: Components.Headers.TracingHeader? = nil @@ -986,12 +1002,14 @@ public enum Operations { public var query: Operations.createPet.Input.Query /// - Remark: Generated from `#/paths/pets/POST/header`. public struct Headers: Sendable, Equatable, Hashable { + /// A description here. + /// /// - Remark: Generated from `#/paths/pets/POST/header/X-Extra-Arguments`. public var X_Extra_Arguments: Components.Schemas.CodeError? /// Creates a new `Headers`. /// /// - Parameters: - /// - X_Extra_Arguments: + /// - X_Extra_Arguments: A description here. public init(X_Extra_Arguments: Components.Schemas.CodeError? = nil) { self.X_Extra_Arguments = X_Extra_Arguments } @@ -1035,12 +1053,14 @@ public enum Operations { public struct Created: Sendable, Equatable, Hashable { /// - Remark: Generated from `#/paths/pets/POST/responses/201/headers`. public struct Headers: Sendable, Equatable, Hashable { + /// A description here. + /// /// - Remark: Generated from `#/paths/pets/POST/responses/201/headers/X-Extra-Arguments`. public var X_Extra_Arguments: Components.Schemas.CodeError? /// Creates a new `Headers`. /// /// - Parameters: - /// - X_Extra_Arguments: + /// - X_Extra_Arguments: A description here. public init(X_Extra_Arguments: Components.Schemas.CodeError? = nil) { self.X_Extra_Arguments = X_Extra_Arguments } @@ -1376,12 +1396,14 @@ public enum Operations { public struct Input: Sendable, Equatable, Hashable { /// - Remark: Generated from `#/paths/pets/{petId}/PATCH/path`. public struct Path: Sendable, Equatable, Hashable { + /// Id of the pet + /// /// - Remark: Generated from `#/paths/pets/{petId}/PATCH/path/petId`. public var petId: Swift.Int64 /// Creates a new `Path`. /// /// - Parameters: - /// - petId: + /// - petId: Id of the pet public init(petId: Swift.Int64) { self.petId = petId } } public var path: Operations.updatePet.Input.Path @@ -1518,12 +1540,14 @@ public enum Operations { public struct Input: Sendable, Equatable, Hashable { /// - Remark: Generated from `#/paths/pets/{petId}/avatar/PUT/path`. public struct Path: Sendable, Equatable, Hashable { + /// The id of the pet to retrieve + /// /// - Remark: Generated from `#/paths/pets/{petId}/avatar/PUT/path/petId`. public var petId: Components.Parameters.path_petId /// Creates a new `Path`. /// /// - Parameters: - /// - petId: + /// - petId: The id of the pet to retrieve public init(petId: Components.Parameters.path_petId) { self.petId = petId } } public var path: Operations.uploadAvatarForPet.Input.Path diff --git a/Tests/OpenAPIGeneratorReferenceTests/Resources/ReferenceSources/Petstore_FF_MultipleContentTypes/Types.swift b/Tests/OpenAPIGeneratorReferenceTests/Resources/ReferenceSources/Petstore_FF_MultipleContentTypes/Types.swift index b920c11f..88ed6eb8 100644 --- a/Tests/OpenAPIGeneratorReferenceTests/Resources/ReferenceSources/Petstore_FF_MultipleContentTypes/Types.swift +++ b/Tests/OpenAPIGeneratorReferenceTests/Resources/ReferenceSources/Petstore_FF_MultipleContentTypes/Types.swift @@ -590,6 +590,8 @@ public enum Components { @frozen public enum UpdatePetRequest: Sendable, Equatable, Hashable { /// - Remark: Generated from `#/components/requestBodies/UpdatePetRequest/json`. public struct jsonPayload: Codable, Equatable, Hashable, Sendable { + /// Pet name + /// /// - Remark: Generated from `#/components/requestBodies/UpdatePetRequest/json/name`. public var name: Swift.String? /// - Remark: Generated from `#/components/requestBodies/UpdatePetRequest/json/kind`. @@ -599,7 +601,7 @@ public enum Components { /// Creates a new `jsonPayload`. /// /// - Parameters: - /// - name: + /// - name: Pet name /// - kind: /// - tag: public init( @@ -626,12 +628,14 @@ public enum Components { public struct ErrorBadRequest: Sendable, Equatable, Hashable { /// - Remark: Generated from `#/components/responses/ErrorBadRequest/headers`. public struct Headers: Sendable, Equatable, Hashable { + /// A description here. + /// /// - Remark: Generated from `#/components/responses/ErrorBadRequest/headers/X-Reason`. public var X_hyphen_Reason: Swift.String? /// Creates a new `Headers`. /// /// - Parameters: - /// - X_hyphen_Reason: + /// - X_hyphen_Reason: A description here. public init(X_hyphen_Reason: Swift.String? = nil) { self.X_hyphen_Reason = X_hyphen_Reason } @@ -672,6 +676,8 @@ public enum Components { } /// Types generated from the `#/components/headers` section of the OpenAPI document. public enum Headers { + /// A description here. + /// /// - Remark: Generated from `#/components/headers/TracingHeader`. public typealias TracingHeader = Swift.String } @@ -696,6 +702,8 @@ public enum Operations { public var path: Operations.listPets.Input.Path /// - Remark: Generated from `#/paths/pets/GET/query`. public struct Query: Sendable, Equatable, Hashable { + /// How many items to return at one time (max 100) + /// /// - Remark: Generated from `#/paths/pets/GET/query/limit`. public var limit: Swift.Int32? /// - Remark: Generated from `#/paths/pets/GET/query/habitat`. @@ -724,15 +732,17 @@ public enum Operations { .feedsPayloadPayload] /// - Remark: Generated from `#/paths/pets/GET/query/feeds`. public var feeds: Operations.listPets.Input.Query.feedsPayload? + /// Supply this parameter to filter pets born since the provided date. + /// /// - Remark: Generated from `#/paths/pets/GET/query/since`. public var since: Components.Parameters.query_period_born_hyphen_since? /// Creates a new `Query`. /// /// - Parameters: - /// - limit: + /// - limit: How many items to return at one time (max 100) /// - habitat: /// - feeds: - /// - since: + /// - since: Supply this parameter to filter pets born since the provided date. public init( limit: Swift.Int32? = nil, habitat: Operations.listPets.Input.Query.habitatPayload? = nil, @@ -748,12 +758,14 @@ public enum Operations { public var query: Operations.listPets.Input.Query /// - Remark: Generated from `#/paths/pets/GET/header`. public struct Headers: Sendable, Equatable, Hashable { + /// Request identifier + /// /// - Remark: Generated from `#/paths/pets/GET/header/My-Request-UUID`. public var My_hyphen_Request_hyphen_UUID: Swift.String? /// Creates a new `Headers`. /// /// - Parameters: - /// - My_hyphen_Request_hyphen_UUID: + /// - My_hyphen_Request_hyphen_UUID: Request identifier public init(My_hyphen_Request_hyphen_UUID: Swift.String? = nil) { self.My_hyphen_Request_hyphen_UUID = My_hyphen_Request_hyphen_UUID } @@ -794,15 +806,19 @@ public enum Operations { public struct Ok: Sendable, Equatable, Hashable { /// - Remark: Generated from `#/paths/pets/GET/responses/200/headers`. public struct Headers: Sendable, Equatable, Hashable { + /// Response identifier + /// /// - Remark: Generated from `#/paths/pets/GET/responses/200/headers/My-Response-UUID`. public var My_hyphen_Response_hyphen_UUID: Swift.String + /// A description here. + /// /// - Remark: Generated from `#/paths/pets/GET/responses/200/headers/My-Tracing-Header`. public var My_hyphen_Tracing_hyphen_Header: Components.Headers.TracingHeader? /// Creates a new `Headers`. /// /// - Parameters: - /// - My_hyphen_Response_hyphen_UUID: - /// - My_hyphen_Tracing_hyphen_Header: + /// - My_hyphen_Response_hyphen_UUID: Response identifier + /// - My_hyphen_Tracing_hyphen_Header: A description here. public init( My_hyphen_Response_hyphen_UUID: Swift.String, My_hyphen_Tracing_hyphen_Header: Components.Headers.TracingHeader? = nil @@ -896,12 +912,14 @@ public enum Operations { public var query: Operations.createPet.Input.Query /// - Remark: Generated from `#/paths/pets/POST/header`. public struct Headers: Sendable, Equatable, Hashable { + /// A description here. + /// /// - Remark: Generated from `#/paths/pets/POST/header/X-Extra-Arguments`. public var X_hyphen_Extra_hyphen_Arguments: Components.Schemas.CodeError? /// Creates a new `Headers`. /// /// - Parameters: - /// - X_hyphen_Extra_hyphen_Arguments: + /// - X_hyphen_Extra_hyphen_Arguments: A description here. public init(X_hyphen_Extra_hyphen_Arguments: Components.Schemas.CodeError? = nil) { self.X_hyphen_Extra_hyphen_Arguments = X_hyphen_Extra_hyphen_Arguments } @@ -945,12 +963,14 @@ public enum Operations { public struct Created: Sendable, Equatable, Hashable { /// - Remark: Generated from `#/paths/pets/POST/responses/201/headers`. public struct Headers: Sendable, Equatable, Hashable { + /// A description here. + /// /// - Remark: Generated from `#/paths/pets/POST/responses/201/headers/X-Extra-Arguments`. public var X_hyphen_Extra_hyphen_Arguments: Components.Schemas.CodeError? /// Creates a new `Headers`. /// /// - Parameters: - /// - X_hyphen_Extra_hyphen_Arguments: + /// - X_hyphen_Extra_hyphen_Arguments: A description here. public init( X_hyphen_Extra_hyphen_Arguments: Components.Schemas.CodeError? = nil ) { self.X_hyphen_Extra_hyphen_Arguments = X_hyphen_Extra_hyphen_Arguments } @@ -1294,12 +1314,14 @@ public enum Operations { public struct Input: Sendable, Equatable, Hashable { /// - Remark: Generated from `#/paths/pets/{petId}/PATCH/path`. public struct Path: Sendable, Equatable, Hashable { + /// Id of the pet + /// /// - Remark: Generated from `#/paths/pets/{petId}/PATCH/path/petId`. public var petId: Swift.Int64 /// Creates a new `Path`. /// /// - Parameters: - /// - petId: + /// - petId: Id of the pet public init(petId: Swift.Int64) { self.petId = petId } } public var path: Operations.updatePet.Input.Path @@ -1436,12 +1458,14 @@ public enum Operations { public struct Input: Sendable, Equatable, Hashable { /// - Remark: Generated from `#/paths/pets/{petId}/avatar/PUT/path`. public struct Path: Sendable, Equatable, Hashable { + /// The id of the pet to retrieve + /// /// - Remark: Generated from `#/paths/pets/{petId}/avatar/PUT/path/petId`. public var petId: Components.Parameters.path_period_petId /// Creates a new `Path`. /// /// - Parameters: - /// - petId: + /// - petId: The id of the pet to retrieve public init(petId: Components.Parameters.path_period_petId) { self.petId = petId } } public var path: Operations.uploadAvatarForPet.Input.Path