From f3290d6a528974d0209e054f54d162e1bfa8ab99 Mon Sep 17 00:00:00 2001 From: Mathieu Barnachon Date: Thu, 29 Aug 2019 12:10:29 +0200 Subject: [PATCH 1/3] Move to public the `SwaggerDocument` object of the router. Add `title`, `description` and `version` to the constructer in order to be specified by the user. Add a related test. --- Sources/Kitura/Router.swift | 2 +- Sources/Kitura/SwaggerGenerator.swift | 8 +++-- Tests/KituraTests/TestSwaggerGeneration.swift | 36 +++++++++++++++++++ 3 files changed, 42 insertions(+), 4 deletions(-) diff --git a/Sources/Kitura/Router.swift b/Sources/Kitura/Router.swift index 07c0bc602..6b0468590 100644 --- a/Sources/Kitura/Router.swift +++ b/Sources/Kitura/Router.swift @@ -120,7 +120,7 @@ public class Router { // MARK: Swagger /// Contains the structures needed for swagger document generation - var swagger: SwaggerDocument + public var swagger: SwaggerDocument /// Returns the current in-memory representation of Codable routes as a /// Swagger document in JSON format, or nil if the document cannot be diff --git a/Sources/Kitura/SwaggerGenerator.swift b/Sources/Kitura/SwaggerGenerator.swift index b736506c8..be14342d2 100644 --- a/Sources/Kitura/SwaggerGenerator.swift +++ b/Sources/Kitura/SwaggerGenerator.swift @@ -348,7 +348,7 @@ enum SwiftType: String { } } -struct SwaggerDocument: Encodable { +public struct SwaggerDocument: Encodable { // swagger document is the conatiner for all the openAPI information that we // can gather from the Kitura server. Once data is written to the structures // in SwaggerDocument, a call to toDocument() is used to write the document @@ -373,9 +373,11 @@ struct SwaggerDocument: Encodable { private var dateEncodingStrategy: JSONEncoder.DateEncodingStrategy = .deferredToDate private var dateDecodingStrategy: JSONDecoder.DateDecodingStrategy = .deferredToDate - public init() { + public init(title: String = "Kitura Project", + description: String = "Generated by Kitura", + version: String = "1.0") { self.swagger = "2.0" - self.info = SwaggerInfo(version: "1.0", description: "Generated by Kitura", title: "Kitura Project") + self.info = SwaggerInfo(version: version, description: description, title: title) self.basePath = "/" self.schemes = [] // The valid schemes will be populated later, at serialisation time self.paths = [:] diff --git a/Tests/KituraTests/TestSwaggerGeneration.swift b/Tests/KituraTests/TestSwaggerGeneration.swift index b00bcd94b..ab538f61d 100644 --- a/Tests/KituraTests/TestSwaggerGeneration.swift +++ b/Tests/KituraTests/TestSwaggerGeneration.swift @@ -168,6 +168,7 @@ final class TestSwaggerGeneration: KituraTest, KituraTestSuite { ("testSwaggerVersion", testSwaggerVersion), ("testBasePath", testBasePath), ("testInfo", testInfo), + ("testCustomInfo", testCustomInfo), ("testSwaggerDefinitions", testSwaggerDefinitions), ("testSwaggerContent", testSwaggerContent), ("testSwaggerQueryParams", testSwaggerQueryParams), @@ -1019,6 +1020,41 @@ final class TestSwaggerGeneration: KituraTest, KituraTestSuite { } } } + + // + // Test that our swagger document defines the custom info section. + // + func testCustomInfo() { + let customTitle = "My Project" + let customDescription = "My project generated by Kitura" + let customVersion = "0.0.1" + let localRouter = Router() + localRouter.swagger = SwaggerDocument(title: customTitle, + description: customDescription, + version: customVersion) + guard let dict = getSwaggerDictionary(for: localRouter) else { + return XCTFail("Unable to get swagger dictionary") + } + if let info = dict["info"] as? [String: String] { + if let title = info["title"] { + XCTAssertTrue(title == customTitle, "title is incorrect") + } else { + XCTFail("title is missing") + } + + if let desc = info["description"] { + XCTAssertTrue(desc == customDescription, "description is incorrect") + } else { + XCTFail("description is missing") + } + + if let version = info["version"] { + XCTAssertTrue(version == customVersion, "version is incorrect") + } else { + XCTFail("version is missing") + } + } + } // // Test that our swagger document contains the expected paths From 514f68a0297799b4bd3cf6188832bd1b51763b81 Mon Sep 17 00:00:00 2001 From: Mathieu Barnachon Date: Tue, 10 Sep 2019 10:03:00 +0200 Subject: [PATCH 2/3] Keep the SwaggerDocument internal and add an API document parameter to the router initialiser. --- Sources/Kitura/Router.swift | 6 +++--- Tests/KituraTests/TestSwaggerGeneration.swift | 7 +++---- 2 files changed, 6 insertions(+), 7 deletions(-) diff --git a/Sources/Kitura/Router.swift b/Sources/Kitura/Router.swift index 6b0468590..80c609b46 100644 --- a/Sources/Kitura/Router.swift +++ b/Sources/Kitura/Router.swift @@ -92,8 +92,8 @@ public class Router { /// FileResourceServer to serve the default /// "Welcome to Kitura" page and related /// assets. - public init(mergeParameters: Bool = false, enableWelcomePage: Bool = true) { - self.swagger = SwaggerDocument() + public init(mergeParameters: Bool = false, enableWelcomePage: Bool = true, apiDocument: SwaggerDocument = SwaggerDocument()) { + self.swagger = apiDocument self.mergeParameters = mergeParameters self.fileResourceServer = enableWelcomePage ? FileResourceServer() : nil @@ -120,7 +120,7 @@ public class Router { // MARK: Swagger /// Contains the structures needed for swagger document generation - public var swagger: SwaggerDocument + internal var swagger: SwaggerDocument /// Returns the current in-memory representation of Codable routes as a /// Swagger document in JSON format, or nil if the document cannot be diff --git a/Tests/KituraTests/TestSwaggerGeneration.swift b/Tests/KituraTests/TestSwaggerGeneration.swift index ab538f61d..c9c29147b 100644 --- a/Tests/KituraTests/TestSwaggerGeneration.swift +++ b/Tests/KituraTests/TestSwaggerGeneration.swift @@ -1028,10 +1028,9 @@ final class TestSwaggerGeneration: KituraTest, KituraTestSuite { let customTitle = "My Project" let customDescription = "My project generated by Kitura" let customVersion = "0.0.1" - let localRouter = Router() - localRouter.swagger = SwaggerDocument(title: customTitle, - description: customDescription, - version: customVersion) + let localRouter = Router(apiDocument: SwaggerDocument(title: customTitle, + description: customDescription, + version: customVersion)) guard let dict = getSwaggerDictionary(for: localRouter) else { return XCTFail("Unable to get swagger dictionary") } From 6d15cc9d553beb8e2a019dc5012328007125942b Mon Sep 17 00:00:00 2001 From: Mathieu Barnachon Date: Tue, 10 Sep 2019 11:36:46 +0200 Subject: [PATCH 3/3] Adding documentation to `apiDocument` parameter. Removing implicit `internal` qualifier. --- Sources/Kitura/Router.swift | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/Sources/Kitura/Router.swift b/Sources/Kitura/Router.swift index 80c609b46..3e61d8df4 100644 --- a/Sources/Kitura/Router.swift +++ b/Sources/Kitura/Router.swift @@ -92,6 +92,8 @@ public class Router { /// FileResourceServer to serve the default /// "Welcome to Kitura" page and related /// assets. + /// - Parameter apiDocument: Optional parameter that allows customization of the OpenAPI document + /// describing this Router. public init(mergeParameters: Bool = false, enableWelcomePage: Bool = true, apiDocument: SwaggerDocument = SwaggerDocument()) { self.swagger = apiDocument self.mergeParameters = mergeParameters @@ -120,7 +122,7 @@ public class Router { // MARK: Swagger /// Contains the structures needed for swagger document generation - internal var swagger: SwaggerDocument + var swagger: SwaggerDocument /// Returns the current in-memory representation of Codable routes as a /// Swagger document in JSON format, or nil if the document cannot be