Merge branch 'develop' into release

SMILEY4 · SMILEY4 · commit 5de8a9bf0314 · 2024-07-11T17:32:55.000+02:00
diff --git a/README.md b/README.md
@@ -56,6 +56,18 @@ install(SwaggerUI) {
     }
 }
 ```
+```kotlin
+routing {
+    // Create a route for the openapi-spec file.
+    route("api.json") {
+      openApiSpec()
+    }
+    // Create a route for the swagger-ui using the openapi-spec at "/api.json".
+    route("swagger") {
+      swaggerUI("/api.json")
+    }
+}
+```
 
 ### Routes
 
diff --git a/gradle.properties b/gradle.properties
@@ -3,7 +3,7 @@ kotlin.code.style=official
 # project id
 projectGroupId=io.github.smiley4
 projectArtifactIdBase=ktor-swagger-ui
-projectVersion=3.1.0
+projectVersion=3.2.0
 
 # publishing information
 projectNameBase=Ktor Swagger UI
diff --git a/ktor-swagger-ui-examples/src/main/kotlin/io/github/smiley4/ktorswaggerui/examples/Authentication.kt b/ktor-swagger-ui-examples/src/main/kotlin/io/github/smiley4/ktorswaggerui/examples/Authentication.kt
@@ -49,7 +49,7 @@ private fun Application.myModule() {
                 scheme = AuthScheme.BASIC
             }
             // if no other security scheme is specified for a route, the one with this name is used instead
-            defaultSecuritySchemeNames = setOf("MySecurityScheme")
+            defaultSecuritySchemeNames("MySecurityScheme")
             // if no other response is documented for "401 Unauthorized", this information is used instead
             defaultUnauthorizedResponse {
                 description = "Username or password is invalid"
@@ -88,7 +88,7 @@ private fun Application.myModule() {
         // route is not in an "authenticate"-block and "protected"-flag is not set
         // -> security schemes will be ignored and not default "401 Unauthorized" response is added
         get("unprotected", {
-            securitySchemeNames = listOf("MySecurityScheme")
+            securitySchemeNames("MySecurityScheme")
         }) {
             call.respondText("Hello World!")
         }
diff --git a/ktor-swagger-ui-examples/src/main/kotlin/io/github/smiley4/ktorswaggerui/examples/Basics.kt b/ktor-swagger-ui-examples/src/main/kotlin/io/github/smiley4/ktorswaggerui/examples/Basics.kt
@@ -70,7 +70,7 @@ private fun Application.myModule() {
             // information about possible responses
             response {
                 // information about a "200 OK" response
-                HttpStatusCode.OK to {
+                code(HttpStatusCode.OK) {
                     // a description of the response
                     description = "successful request - always returns 'Hello World!'"
                 }
diff --git a/ktor-swagger-ui-examples/src/main/kotlin/io/github/smiley4/ktorswaggerui/examples/CompleteConfig.kt b/ktor-swagger-ui-examples/src/main/kotlin/io/github/smiley4/ktorswaggerui/examples/CompleteConfig.kt
@@ -91,7 +91,7 @@ private fun Application.myModule() {
             defaultUnauthorizedResponse {
                 description = "Username or password is invalid"
             }
-            defaultSecuritySchemeNames = setOf("MySecurityScheme")
+            defaultSecuritySchemeNames("MySecurityScheme")
             securityScheme("MySecurityScheme") {
                 type = AuthType.HTTP
                 scheme = AuthScheme.BASIC
@@ -157,12 +157,12 @@ private fun Application.myModule() {
             operationId = "hello"
             summary = "hello world route"
             description = "A Hello-World route as an example."
-            tags = setOf("hello", "example")
+            tags("hello", "example")
             specId = PluginConfigDsl.DEFAULT_SPEC_ID
             deprecated = false
             hidden = false
             protected = false
-            securitySchemeNames = emptyList()
+            securitySchemeNames(emptyList())
             externalDocs {
                 url = "example.com/hello"
                 description = "external documentation of 'hello'-route"
@@ -179,7 +179,7 @@ private fun Application.myModule() {
                 body<Unit>()
             }
             response {
-                HttpStatusCode.OK to {
+                code(HttpStatusCode.OK) {
                     description = "successful request - always returns 'Hello World!'"
                     header<String>("x-random") {
                         description = "A header with some random number"
@@ -189,7 +189,7 @@ private fun Application.myModule() {
                     }
                     body<Greeting> {
                         description = "the greeting object with the name of the person to greet."
-                        mediaTypes = setOf(ContentType.Application.Json)
+                        mediaTypes(ContentType.Application.Json)
                         required = true
                     }
                 }
diff --git a/ktor-swagger-ui-examples/src/main/kotlin/io/github/smiley4/ktorswaggerui/examples/CustomizedSchemaGenerator.kt b/ktor-swagger-ui-examples/src/main/kotlin/io/github/smiley4/ktorswaggerui/examples/CustomizedSchemaGenerator.kt
@@ -61,7 +61,7 @@ private fun Application.myModule() {
             // information about the request
             response {
                 // information about a "200 OK" response
-                HttpStatusCode.OK to {
+                code(HttpStatusCode.OK) {
                     // body of the response
                     body<MyResponseBody>()
                 }
diff --git a/ktor-swagger-ui-examples/src/main/kotlin/io/github/smiley4/ktorswaggerui/examples/FileUpload.kt b/ktor-swagger-ui-examples/src/main/kotlin/io/github/smiley4/ktorswaggerui/examples/FileUpload.kt
@@ -48,7 +48,7 @@ private fun Application.myModule() {
         post("single", {
             request {
                 body<File> {
-                    mediaTypes = setOf(
+                    mediaTypes(
                         ContentType.Image.PNG,
                         ContentType.Image.JPEG,
                         ContentType.Image.SVG,
@@ -63,16 +63,16 @@ private fun Application.myModule() {
         post("multipart", {
             request {
                 multipartBody {
-                    mediaTypes = setOf(ContentType.MultiPart.FormData)
+                    mediaTypes(ContentType.MultiPart.FormData)
                     part<File>("first-image",) {
-                        mediaTypes = setOf(
+                        mediaTypes(
                             ContentType.Image.PNG,
                             ContentType.Image.JPEG,
                             ContentType.Image.SVG
                         )
                     }
                     part<File>("second-image") {
-                        mediaTypes = setOf(
+                        mediaTypes(
                             ContentType.Image.PNG,
                             ContentType.Image.JPEG,
                             ContentType.Image.SVG
diff --git a/ktor-swagger-ui-examples/src/main/kotlin/io/github/smiley4/ktorswaggerui/examples/Petstore.kt b/ktor-swagger-ui-examples/src/main/kotlin/io/github/smiley4/ktorswaggerui/examples/Petstore.kt
@@ -78,7 +78,7 @@ private fun Application.myModule() {
                     }
                 }
                 response {
-                    HttpStatusCode.OK to {
+                    code(HttpStatusCode.OK) {
                         body<List<Pet>> {
                             description = "the list of available pets"
                             example("Pet List") {
@@ -130,7 +130,7 @@ private fun Application.myModule() {
                     }
                 }
                 response {
-                    HttpStatusCode.OK to {
+                    code(HttpStatusCode.OK) {
                         body<Pet> {
                             description = "the created pet"
                             example("Bird") {
@@ -175,7 +175,7 @@ private fun Application.myModule() {
                         }
                     }
                     response {
-                        HttpStatusCode.OK to {
+                        code(HttpStatusCode.OK) {
                             body<Pet>{
                                 description = "the pet with the given id"
                                 example("Bird") {
@@ -194,7 +194,7 @@ private fun Application.myModule() {
                                 }
                             }
                         }
-                        HttpStatusCode.NotFound to {
+                        code(HttpStatusCode.NotFound) {
                             description = "the pet with the given id was not found"
                         }
                         default {
@@ -221,10 +221,10 @@ private fun Application.myModule() {
                         }
                     }
                     response {
-                        HttpStatusCode.NoContent to {
+                        code(HttpStatusCode.NoContent) {
                             description = "the pet was successfully deleted"
                         }
-                        HttpStatusCode.NotFound to {
+                        code(HttpStatusCode.NotFound) {
                             description = "the pet with the given id was not found"
                         }
                         default {
diff --git a/ktor-swagger-ui-examples/src/main/kotlin/io/github/smiley4/ktorswaggerui/examples/RequestResponse.kt b/ktor-swagger-ui-examples/src/main/kotlin/io/github/smiley4/ktorswaggerui/examples/RequestResponse.kt
@@ -62,15 +62,15 @@ private fun Application.myModule() {
             // information the possible responses
             response {
                 // document the "200 OK"-response
-                HttpStatusCode.OK to {
+                code(HttpStatusCode.OK) {
                     description = "Calculation was performed successfully."
                     // specify the schema of the response-body and some additional information
                     body<CalculationResult> {
                         description = "the result of an operation together with the original request"
                     }
                 }
                 // document the "422 UnprocessableEntity"-response
-                HttpStatusCode.UnprocessableEntity to {
+                code(HttpStatusCode.UnprocessableEntity) {
                     description = "The requested calculation could not be performed, e.g. due to division by zero."
                 }
             }
diff --git a/ktor-swagger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/builder/example/ExampleContextImpl.kt b/ktor-swagger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/builder/example/ExampleContextImpl.kt
@@ -21,9 +21,11 @@ class ExampleContextImpl(private val encoder: ExampleEncoder?) : ExampleContext
             val example = generateExample(exampleDescriptor, null)
             componentExamples[exampleDescriptor.name] = example
         }
-        config.securityExamples.forEach { exampleDescriptor ->
-            val example = generateExample(exampleDescriptor, null)
-            rootExamples[exampleDescriptor] = example
+        config.securityExamples?.let {
+            it.examples.forEach { exampleDescriptor ->
+                val example = generateExample(exampleDescriptor, it.type)
+                rootExamples[exampleDescriptor] = example
+            }
         }
     }
 
diff --git a/ktor-swagger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/data/ExampleConfigData.kt b/ktor-swagger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/data/ExampleConfigData.kt
@@ -8,14 +8,14 @@ typealias ExampleEncoder = (type: TypeDescriptor?, example: Any?) -> Any?
 
 class ExampleConfigData(
     val sharedExamples: Map<String, ExampleDescriptor>,
-    val securityExamples: List<ExampleDescriptor>,
+    val securityExamples: OpenApiSimpleBodyData?,
     val exampleEncoder: ExampleEncoder?
 ) {
 
     companion object {
         val DEFAULT = ExampleConfigData(
             sharedExamples = emptyMap(),
-            securityExamples = emptyList(),
+            securityExamples = null,
             exampleEncoder = null
         )
     }
diff --git a/ktor-swagger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/dsl/config/ExampleConfig.kt b/ktor-swagger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/dsl/config/ExampleConfig.kt
@@ -14,12 +14,26 @@ class ExampleConfig {
     val sharedExamples = mutableMapOf<String, ExampleDescriptor>()
     var exampleEncoder: ExampleEncoder? = null
 
+
+    /**
+     * Add a shared example that can be referenced by all routes.
+     * The name of the example has to be unique among all shared examples and acts as its id.
+     * @param example the example data.
+     */
     fun example(example: ExampleDescriptor) {
         sharedExamples[example.name] = example
     }
 
+    /**
+     * Add a shared example that can be referenced by all routes by the given name.
+     * The provided name has to be unique among all shared examples and acts as its id.
+     */
     fun example(name: String, example: Example) = example(SwaggerExampleDescriptor(name, example))
 
+    /**
+     * Add a shared example that can be referenced by all routes by the given name.
+     * The provided name has to be unique among all shared examples and acts as its id.
+     */
     fun example(name: String, example: ValueExampleDescriptorDsl.() -> Unit) = example(
         ValueExampleDescriptorDsl()
             .apply(example)
@@ -33,6 +47,10 @@ class ExampleConfig {
             }
     )
 
+
+    /**
+     * Specify a custom encoder for example objects
+     */
     fun encoder(exampleEncoder: ExampleEncoder) {
         this.exampleEncoder = exampleEncoder
     }
@@ -41,10 +59,10 @@ class ExampleConfig {
         sharedExamples = sharedExamples,
         securityExamples = securityConfig.defaultUnauthorizedResponse?.body?.let {
             when (it) {
-                is OpenApiSimpleBodyData -> it.examples
-                is OpenApiMultipartBodyData -> emptyList()
+                is OpenApiSimpleBodyData -> it
+                is OpenApiMultipartBodyData -> null
             }
-        } ?: emptyList(),
+        },
         exampleEncoder = exampleEncoder
     )
 }
diff --git a/ktor-swagger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/dsl/config/OpenApiSecurity.kt b/ktor-swagger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/dsl/config/OpenApiSecurity.kt
@@ -29,6 +29,19 @@ class OpenApiSecurity {
      */
     var defaultSecuritySchemeNames: Collection<String>? = SecurityData.DEFAULT.defaultSecuritySchemeNames
 
+    /**
+     * Set the names of the security schemes available for use for the protected paths
+     */
+    fun defaultSecuritySchemeNames(names: Collection<String>) {
+        this.defaultSecuritySchemeNames = names
+    }
+
+    /**
+     * Set the names of the security schemes available for use for the protected paths
+     */
+    fun defaultSecuritySchemeNames(vararg names: String) {
+        this.defaultSecuritySchemeNames = names.toList()
+    }
 
     /**
      * Defines security schemes that can be used by operations
diff --git a/ktor-swagger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/dsl/config/SchemaConfig.kt b/ktor-swagger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/dsl/config/SchemaConfig.kt
@@ -13,32 +13,74 @@ import kotlin.reflect.typeOf
 @OpenApiDslMarker
 class SchemaConfig {
 
+    /**
+     * The json-schema generator for all schemas. See https://github.com/SMILEY4/schema-kenerator/wiki for more information.
+     */
     var generator: (type: KType) -> CompiledSwaggerSchema = SchemaConfigData.DEFAULT.generator
 
-    val schemas = mutableMapOf<String, TypeDescriptor>()
+    private val schemas = mutableMapOf<String, TypeDescriptor>()
 
-    val overwrite = mutableMapOf<KType, TypeDescriptor>()
+    private val overwrite = mutableMapOf<KType, TypeDescriptor>()
 
+
+    /**
+     * Overwrite the given [type] with the given [replacement].
+     * When the type is specified as the type of a schema, the replacement is used instead.
+     * This only works for "root"-types and not types of e.g. nested fields.
+     */
     fun overwrite(type: KType, replacement: TypeDescriptor) {
         overwrite[type] = replacement
     }
 
+    /**
+     * Overwrite the given type [T] with the given [replacement].
+     * When the type is specified as the type of a schema, the replacement is used instead.
+     * This only works for "root"-types and not types of e.g. nested fields.
+     */
     inline fun <reified T> overwrite(replacement: TypeDescriptor) = overwrite(typeOf<T>(), replacement)
 
+    /**
+     * Overwrite the given type [T] with the given [replacement].
+     * When the type is specified as the type of a schema, the replacement is used instead.
+     * This only works for "root"-types and not types of e.g. nested fields.
+     */
     inline fun <reified T> overwrite(replacement: Schema<*>) = overwrite(typeOf<T>(), SwaggerTypeDescriptor(replacement))
 
+    /**
+     * Overwrite the given type [T] with the given [replacement].
+     * When the type is specified as the type of a schema, the replacement is used instead.
+     * This only works for "root"-types and not types of e.g. nested fields.
+     */
     inline fun <reified T> overwrite(replacement: KType) = overwrite(typeOf<T>(), KTypeDescriptor(replacement))
 
+    /**
+     * Overwrite the given type [T] with the given replacement [R].
+     * When the type is specified as the type of a schema, the replacement is used instead.
+     * This only works for "root"-types and not types of e.g. nested fields.
+     */
     inline fun <reified T, reified R> overwrite() = overwrite(typeOf<T>(), KTypeDescriptor(typeOf<R>()))
 
+
+    /**
+     * Add a shared schema that can be referenced by all routes by the given id.
+     */
     fun schema(schemaId: String, descriptor: TypeDescriptor) {
         schemas[schemaId] = descriptor
     }
 
+    /**
+     * Add a shared schema that can be referenced by all routes by the given id.
+     */
     fun schema(schemaId: String, schema: Schema<*>) = schema(schemaId, SwaggerTypeDescriptor(schema))
 
+    /**
+     * Add a shared schema that can be referenced by all routes by the given id.
+     */
     fun schema(schemaId: String, schema: KType) = schema(schemaId, KTypeDescriptor(schema))
 
+    /**
+     * Add a shared schema that can be referenced by all routes by the given id.
+     */
     inline fun <reified T> schema(schemaId: String) = schema(schemaId, KTypeDescriptor(typeOf<T>()))
 
     fun build(securityConfig: SecurityData) = SchemaConfigData(
diff --git a/ktor-swagger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/dsl/routes/OpenApiBaseBody.kt b/ktor-swagger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/dsl/routes/OpenApiBaseBody.kt
diff --git a/ktor-swagger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/dsl/routes/OpenApiMultipartPart.kt b/ktor-swagger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/dsl/routes/OpenApiMultipartPart.kt
diff --git a/ktor-swagger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/dsl/routes/OpenApiResponses.kt b/ktor-swagger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/dsl/routes/OpenApiResponses.kt
diff --git a/ktor-swagger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/dsl/routes/OpenApiRoute.kt b/ktor-swagger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/dsl/routes/OpenApiRoute.kt
diff --git a/src/main/kotlin/io/github/smiley4/ktorswaggerui/routing/ControllerUtils.kt b/src/main/kotlin/io/github/smiley4/ktorswaggerui/routing/ControllerUtils.kt

Original file line number	Diff line number	Diff line change
`@@ -70,7 +70,7 @@ private fun Application.myModule() {`
`70`	`70`	`// information about possible responses`
`71`	`71`	`response {`
`72`	`72`	`// information about a "200 OK" response`
`73`		`- HttpStatusCode.OK to {`
	`73`	`+ code(HttpStatusCode.OK) {`
`74`	`74`	`// a description of the response`
`75`	`75`	`description = "successful request - always returns 'Hello World!'"`
`76`	`76`	`}`
Original file line number	Diff line number	Diff line change
`@@ -61,7 +61,7 @@ private fun Application.myModule() {`
`61`	`61`	`// information about the request`
`62`	`62`	`response {`
`63`	`63`	`// information about a "200 OK" response`
`64`		`- HttpStatusCode.OK to {`
	`64`	`+ code(HttpStatusCode.OK) {`
`65`	`65`	`// body of the response`
`66`	`66`	`body<MyResponseBody>()`
`67`	`67`	`}`
Original file line number	Diff line number	Diff line change
`@@ -78,7 +78,7 @@ private fun Application.myModule() {`
`78`	`78`	`}`
`79`	`79`	`}`
`80`	`80`	`response {`
`81`		`- HttpStatusCode.OK to {`
	`81`	`+ code(HttpStatusCode.OK) {`
`82`	`82`	`body<List<Pet>> {`
`83`	`83`	`description = "the list of available pets"`
`84`	`84`	`example("Pet List") {`
`@@ -130,7 +130,7 @@ private fun Application.myModule() {`
`130`	`130`	`}`
`131`	`131`	`}`
`132`	`132`	`response {`
`133`		`- HttpStatusCode.OK to {`
	`133`	`+ code(HttpStatusCode.OK) {`
`134`	`134`	`body<Pet> {`
`135`	`135`	`description = "the created pet"`
`136`	`136`	`example("Bird") {`
`@@ -175,7 +175,7 @@ private fun Application.myModule() {`
`175`	`175`	`}`
`176`	`176`	`}`
`177`	`177`	`response {`
`178`		`- HttpStatusCode.OK to {`
	`178`	`+ code(HttpStatusCode.OK) {`
`179`	`179`	`body<Pet>{`
`180`	`180`	`description = "the pet with the given id"`
`181`	`181`	`example("Bird") {`
`@@ -194,7 +194,7 @@ private fun Application.myModule() {`
`194`	`194`	`}`
`195`	`195`	`}`
`196`	`196`	`}`
`197`		`- HttpStatusCode.NotFound to {`
	`197`	`+ code(HttpStatusCode.NotFound) {`
`198`	`198`	`description = "the pet with the given id was not found"`
`199`	`199`	`}`
`200`	`200`	`default {`
`@@ -221,10 +221,10 @@ private fun Application.myModule() {`
`221`	`221`	`}`
`222`	`222`	`}`
`223`	`223`	`response {`
`224`		`- HttpStatusCode.NoContent to {`
	`224`	`+ code(HttpStatusCode.NoContent) {`
`225`	`225`	`description = "the pet was successfully deleted"`
`226`	`226`	`}`
`227`		`- HttpStatusCode.NotFound to {`
	`227`	`+ code(HttpStatusCode.NotFound) {`
`228`	`228`	`description = "the pet with the given id was not found"`
`229`	`229`	`}`
`230`	`230`	`default {`
Original file line number	Diff line number	Diff line change
`@@ -62,15 +62,15 @@ private fun Application.myModule() {`
`62`	`62`	`// information the possible responses`
`63`	`63`	`response {`
`64`	`64`	`// document the "200 OK"-response`
`65`		`- HttpStatusCode.OK to {`
	`65`	`+ code(HttpStatusCode.OK) {`
`66`	`66`	`description = "Calculation was performed successfully."`
`67`	`67`	`// specify the schema of the response-body and some additional information`
`68`	`68`	`body<CalculationResult> {`
`69`	`69`	`description = "the result of an operation together with the original request"`
`70`	`70`	`}`
`71`	`71`	`}`
`72`	`72`	`// document the "422 UnprocessableEntity"-response`
`73`		`- HttpStatusCode.UnprocessableEntity to {`
	`73`	`+ code(HttpStatusCode.UnprocessableEntity) {`
`74`	`74`	`description = "The requested calculation could not be performed, e.g. due to division by zero."`
`75`	`75`	`}`
`76`	`76`	`}`
Original file line number	Diff line number	Diff line change
`@@ -21,9 +21,11 @@ class ExampleContextImpl(private val encoder: ExampleEncoder?) : ExampleContext`
`21`	`21`	`val example = generateExample(exampleDescriptor, null)`
`22`	`22`	`componentExamples[exampleDescriptor.name] = example`
`23`	`23`	`}`
`24`		`- config.securityExamples.forEach { exampleDescriptor ->`
`25`		`- val example = generateExample(exampleDescriptor, null)`
`26`		`- rootExamples[exampleDescriptor] = example`
	`24`	`+ config.securityExamples?.let {`
	`25`	`+ it.examples.forEach { exampleDescriptor ->`
	`26`	`+ val example = generateExample(exampleDescriptor, it.type)`
	`27`	`+ rootExamples[exampleDescriptor] = example`
	`28`	`+ }`
`27`	`29`	`}`
`28`	`30`	`}`
`29`	`31`