diff --git a/ktor-swagger-ui-examples/build.gradle.kts b/ktor-swagger-ui-examples/build.gradle.kts index 9c7f459..8109498 100644 --- a/ktor-swagger-ui-examples/build.gradle.kts +++ b/ktor-swagger-ui-examples/build.gradle.kts @@ -5,6 +5,7 @@ version = projectVersion plugins { kotlin("jvm") + kotlin("plugin.serialization") version "1.9.21" } repositories { @@ -29,6 +30,7 @@ dependencies { implementation("io.github.smiley4:schema-kenerator-core:$versionSchemaKenerator") implementation("io.github.smiley4:schema-kenerator-reflection:$versionSchemaKenerator") + implementation("io.github.smiley4:schema-kenerator-serialization:$versionSchemaKenerator") implementation("io.github.smiley4:schema-kenerator-swagger:$versionSchemaKenerator") implementation("io.github.smiley4:schema-kenerator-jackson:$versionSchemaKenerator") 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 new file mode 100644 index 0000000..5940244 --- /dev/null +++ b/ktor-swagger-ui-examples/src/main/kotlin/io/github/smiley4/ktorswaggerui/examples/CustomizedSchemaGenerator.kt @@ -0,0 +1,80 @@ +package io.github.smiley4.ktorswaggerui.examples + +import io.github.smiley4.ktorswaggerui.SwaggerUI +import io.github.smiley4.ktorswaggerui.dsl.routing.get +import io.github.smiley4.ktorswaggerui.routing.openApiSpec +import io.github.smiley4.ktorswaggerui.routing.swaggerUI +import io.github.smiley4.schemakenerator.serialization.processKotlinxSerialization +import io.github.smiley4.schemakenerator.swagger.compileReferencingRoot +import io.github.smiley4.schemakenerator.swagger.data.TitleType +import io.github.smiley4.schemakenerator.swagger.generateSwaggerSchema +import io.github.smiley4.schemakenerator.swagger.withAutoTitle +import io.ktor.http.HttpStatusCode +import io.ktor.server.application.Application +import io.ktor.server.application.call +import io.ktor.server.application.install +import io.ktor.server.engine.embeddedServer +import io.ktor.server.netty.Netty +import io.ktor.server.response.respond +import io.ktor.server.routing.route +import io.ktor.server.routing.routing +import kotlinx.serialization.Serializable + +fun main() { + embeddedServer(Netty, port = 8080, host = "localhost", module = Application::myModule).start(wait = true) +} + +private fun Application.myModule() { + + // Install and configure the "SwaggerUI"-Plugin + install(SwaggerUI) { + schemas { + // replace default schema-generator with customized one + generator = { type -> + type + // process type using kotlinx-serialization instead of reflection + // requires additional dependency "io.github.smiley4:schema-kenerator-kotlinx-serialization:" + // see https://github.com/SMILEY4/schema-kenerator for more information + .processKotlinxSerialization() + .generateSwaggerSchema() + .withAutoTitle(TitleType.SIMPLE) + .compileReferencingRoot() + } + } + } + + routing { + + // Create a route for the swagger-ui using the openapi-spec at "/api.json". + // This route will not be included in the spec. + route("swagger") { + swaggerUI("/api.json") + } + // Create a route for the openapi-spec file. + // This route will not be included in the spec. + route("api.json") { + openApiSpec() + } + + // a documented route + get("hello", { + // information about the request + response { + // information about a "200 OK" response + HttpStatusCode.OK to { + // body of the response + body() + } + } + }) { + call.respond(HttpStatusCode.NotImplemented, "...") + } + + } + +} + +@Serializable +private class MyResponseBody( + val name: String, +) \ No newline at end of file diff --git a/ktor-swagger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/data/SchemaConfigData.kt b/ktor-swagger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/data/SchemaConfigData.kt index 4a667c0..d785074 100644 --- a/ktor-swagger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/data/SchemaConfigData.kt +++ b/ktor-swagger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/data/SchemaConfigData.kt @@ -1,10 +1,14 @@ package io.github.smiley4.ktorswaggerui.data +import io.github.smiley4.schemakenerator.core.connectSubTypes +import io.github.smiley4.schemakenerator.core.handleNameAnnotation +import io.github.smiley4.schemakenerator.reflection.collectSubTypes import io.github.smiley4.schemakenerator.reflection.processReflection import io.github.smiley4.schemakenerator.swagger.compileReferencingRoot import io.github.smiley4.schemakenerator.swagger.data.CompiledSwaggerSchema import io.github.smiley4.schemakenerator.swagger.data.TitleType import io.github.smiley4.schemakenerator.swagger.generateSwaggerSchema +import io.github.smiley4.schemakenerator.swagger.handleCoreAnnotations import io.github.smiley4.schemakenerator.swagger.withAutoTitle import kotlin.reflect.KType @@ -19,8 +23,12 @@ data class SchemaConfigData( schemas = emptyMap(), generator = { type -> type + .collectSubTypes() .processReflection() + .connectSubTypes() + .handleNameAnnotation() .generateSwaggerSchema() + .handleCoreAnnotations() .withAutoTitle(TitleType.SIMPLE) .compileReferencingRoot() }, diff --git a/ktor-swagger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/dsl/config/OpenApiSecurityScheme.kt b/ktor-swagger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/dsl/config/OpenApiSecurityScheme.kt index b2e69f0..83f8bf6 100644 --- a/ktor-swagger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/dsl/config/OpenApiSecurityScheme.kt +++ b/ktor-swagger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/dsl/config/OpenApiSecurityScheme.kt @@ -55,7 +55,7 @@ class OpenApiSecurityScheme( /** - * information for the oauth flow types supported. + * Information for the oauth flow types supported. * Required for type [AuthType.OAUTH2] */ fun flows(block: OpenIdOAuthFlows.() -> Unit) { @@ -71,7 +71,7 @@ class OpenApiSecurityScheme( /** - * A short description for security scheme. + * A short description of the security scheme. */ var description: String? = null diff --git a/ktor-swagger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/dsl/config/OpenApiTag.kt b/ktor-swagger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/dsl/config/OpenApiTag.kt index 1f162e0..27b38c6 100644 --- a/ktor-swagger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/dsl/config/OpenApiTag.kt +++ b/ktor-swagger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/dsl/config/OpenApiTag.kt @@ -26,7 +26,7 @@ class OpenApiTag( var externalDocDescription: String? = null /** - *The URL for additional external documentation for this tag. + * The URL for additional external documentation for this tag. */ var externalDocUrl: String? = null diff --git a/ktor-swagger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/dsl/routes/OpenApiHeader.kt b/ktor-swagger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/dsl/routes/OpenApiHeader.kt index 73227c7..e7d9b2e 100644 --- a/ktor-swagger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/dsl/routes/OpenApiHeader.kt +++ b/ktor-swagger-ui/src/main/kotlin/io/github/smiley4/ktorswaggerui/dsl/routes/OpenApiHeader.kt @@ -62,6 +62,10 @@ class OpenApiHeader { */ var deprecated: Boolean? = null + + /** + * Specifies whether arrays and objects should generate separate parameters for each array item or object property. + */ var explode: Boolean? = null fun build() = OpenApiHeaderData( 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 index 558ff95..98d0902 100644 --- 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 @@ -25,7 +25,7 @@ class OpenApiMultipartPart( ) { /** - * Set a specific content type for this part + * Set a specific content types for this part */ var mediaTypes: Collection = setOf()