openapi: adding openApi() to context will now add /openapi.json, /openapi.html and /openapi routes, which will also serve Swagger-UI automatically

Author: angryziber

.idea/gradle.xml

@@ -3,6 +3,7 @@
 * jdbc: improve AlreadyExistsException message (always starts with errors.alreadyExists)
 * jdbc: better handling of comments inside quoted strings in migration scripts
 * csv: support for providing a different encoding than UTF-8 when parsing or generating
+* openapi: adding openApi() to context will now add /openapi.json, /openapi.html and /openapi routes, which will also serve Swagger-UI automatically
 
 # 1.6.14
 * jdbc: add helpful details to Postgres exception "no hstore extension installed"

CHANGELOG.md

@@ -1,6 +1,6 @@
 # klite-openapi
 
-An experimental module to generate OpenAPI spec for klite routes.
+A module to generate OpenAPI spec for Klite routes.
 
 Input/output parameters, paths, names will be generated from annotated route classes automatically.
 Use Swagger/OpenAPI annotations to specify descriptions or more details.
@@ -14,19 +14,19 @@ Usage:
     useOnly<JsonBody>()
     annotated<MyRoutes>()
     // ... more routes
-    openApi(annotations = MyRoutes::class.annotations) // adds /openapi endpoint to the /api context
+    openApi(annotations = MyRoutes::class.annotations) // adds /openapi endpoint to the context
   }
 ```
 
 See [sample Launcher](../sample/src/Launcher.kt).
 
 ## Swagger UI
 
-For nice visual representation of OpenAPI json output:
-* add `before(CorsHandler())` before `openApi()`, as Swagger UI requires CORS to request openapi json from another host/domain
-* `docker run -d -p 8080:8088 swaggerapi/swagger-ui`
-* Open http://localhost:8088/?url=http://YOUR-IP:PORT/api/openapi
-* Alternatively, use https://petstore.swagger.io/?url= if your `/openapi` route is available over https.
+You can request the following endpoints in your context (`/api` in this case):
+
+* `/openapi.json` - will serve Open API json spec
+* `/openapi.html` - will serve Swagger UI
+* `/openapi` - will detect if you are asking for json or html
 
 ## Docs
 

openapi/README.md

@@ -0,0 +1,152 @@
+package klite.openapi
+
+import io.swagger.v3.oas.annotations.Hidden
+import io.swagger.v3.oas.annotations.OpenAPIDefinition
+import io.swagger.v3.oas.annotations.Operation
+import io.swagger.v3.oas.annotations.Parameter
+import io.swagger.v3.oas.annotations.enums.ParameterIn
+import io.swagger.v3.oas.annotations.info.Info
+import io.swagger.v3.oas.annotations.media.Schema.*
+import io.swagger.v3.oas.annotations.parameters.RequestBody
+import io.swagger.v3.oas.annotations.responses.ApiResponse
+import io.swagger.v3.oas.annotations.security.SecurityRequirement
+import io.swagger.v3.oas.annotations.security.SecurityScheme
+import io.swagger.v3.oas.annotations.tags.Tag
+import klite.*
+import klite.StatusCode.Companion.NoContent
+import klite.StatusCode.Companion.OK
+import klite.annotations.*
+import java.net.URI
+import java.net.URL
+import java.time.*
+import java.util.*
+import kotlin.reflect.KClass
+import kotlin.reflect.KParameter.Kind.INSTANCE
+import kotlin.reflect.KProperty1
+import kotlin.reflect.KType
+import kotlin.reflect.KTypeProjection
+import kotlin.reflect.full.*
+
+context(HttpExchange)
+internal fun Router.generateOpenAPI() = mapOf(
+  "openapi" to "3.1.0",
+  "info" to route.findAnnotation<Info>()?.toNonEmptyValues(),
+  "servers" to listOf(mapOf("url" to fullUrl(prefix))),
+  "tags" to toTags(routes),
+  "components" to mapOfNotNull(
+    "securitySchemes" to route.findAnnotations<SecurityScheme>().associate { s ->
+      s.name to s.toNonEmptyValues { it.name != "paramName" }.let { it + ("name" to s.paramName) }
+    }.takeIf { it.isNotEmpty() }
+  ).takeIf { it.isNotEmpty() },
+  "paths" to routes.filter { !it.hasAnnotation<Hidden>() }.groupBy { pathParamRegexer.toOpenApi(it.path) }.mapValues { (_, routes) ->
+    routes.associate(::toOperation)
+  },
+) + (route.findAnnotation<OpenAPIDefinition>()?.let {
+  it.toNonEmptyValues() + ("security" to it.security.toList().toSecurity())
+} ?: emptyMap())
+
+internal fun toTags(routes: List<Route>) = routes.asSequence()
+  .map { it.handler }
+  .filterIsInstance<FunHandler>()
+  .flatMap { it.instance::class.findAnnotations<Tag>().map { it.toNonEmptyValues() }.ifEmpty { listOf(mapOf("name" to it.instance::class.simpleName)) } }
+  .toSet()
+
+internal fun toOperation(route: Route): Pair<String, Any> {
+  val op = route.findAnnotation<Operation>()
+  val funHandler = route.handler as? FunHandler
+  return (op?.method?.trimToNull() ?: route.method.name).lowercase() to mapOf(
+    "operationId" to route.handler.let { (if (it is FunHandler) it.instance::class.simpleName + "." + it.f.name else it::class.simpleName) },
+    "tags" to listOfNotNull(funHandler?.let { it.instance::class.annotation<Tag>()?.name ?: it.instance::class.simpleName }),
+    "parameters" to funHandler?.let {
+      it.params.filter { it.source != null }.map { p -> toParameter(p, op) }
+    },
+    "requestBody" to toRequestBody(route, route.findAnnotation<RequestBody>() ?: op?.requestBody),
+    "responses" to toResponsesByCode(route, op, funHandler?.f?.returnType),
+    "security" to (op?.security?.toList() ?: route.findAnnotations<SecurityRequirement>()).toSecurity()
+  ) + (op?.let { it.toNonEmptyValues { it.name !in setOf("method", "requestBody", "responses") } } ?: emptyMap())
+}
+
+fun toParameter(p: Param, op: Operation? = null) = mapOf(
+  "name" to p.name,
+  "required" to (!p.p.isOptional && !p.p.type.isMarkedNullable),
+  "in" to toParameterIn(p.source),
+  "schema" to p.p.type.toJsonSchema(),
+) + ((p.p.findAnnotation<Parameter>() ?: op?.parameters?.find { it.name == p.name })?.toNonEmptyValues() ?: emptyMap())
+
+private fun toParameterIn(paramAnnotation: Annotation?) = when(paramAnnotation) {
+  is HeaderParam -> ParameterIn.HEADER
+  is QueryParam -> ParameterIn.QUERY
+  is PathParam -> ParameterIn.PATH
+  is CookieParam -> ParameterIn.COOKIE
+  else -> null
+}
+
+private fun KType.toJsonSchema(response: Boolean = false): Map<String, Any?>? {
+  val cls = classifier as? KClass<*> ?: return null
+  return when {
+    cls == Nothing::class -> mapOf("type" to "null")
+    cls == Boolean::class -> mapOf("type" to "boolean")
+    cls == Int::class -> mapOf("type" to "integer", "format" to "int32")
+    cls == Long::class -> mapOf("type" to "integer", "format" to "int64")
+    cls == Float::class -> mapOf("type" to "number", "format" to "float")
+    cls == Double::class -> mapOf("type" to "number", "format" to "double")
+    cls.isSubclassOf(Number::class) -> mapOf("type" to "number")
+    cls.isSubclassOf(Enum::class) -> mapOf("type" to "string", "enum" to cls.java.enumConstants.toList())
+    cls.isSubclassOf(Array::class) || cls.isSubclassOf(Iterable::class) -> mapOf("type" to "array", "items" to arguments.firstOrNull()?.type?.toJsonSchema(response))
+    cls.isSubclassOf(CharSequence::class) || Converter.supports(cls) && cls != Any::class -> mapOfNotNull("type" to "string", "format" to when (cls) {
+      LocalDate::class, Date::class -> "date"
+      LocalTime::class -> "time"
+      Instant::class, LocalDateTime::class -> "date-time"
+      Period::class, Duration::class -> "duration"
+      URI::class, URL::class -> "uri"
+      UUID::class -> "uuid"
+      else -> null
+    })
+    else -> mapOfNotNull("type" to "object",
+      "properties" to cls.publicProperties.associate { it.name to it.returnType.toJsonSchema(response) }.takeIf { it.isNotEmpty() },
+      "required" to cls.publicProperties.filter { p ->
+        !p.returnType.isMarkedNullable && (response || cls.primaryConstructor?.parameters?.find { it.name == p.name }?.isOptional != true)
+      }.map { it.name }.toSet().takeIf { it.isNotEmpty() })
+  }
+}
+
+private fun toRequestBody(route: Route, annotation: RequestBody?): Map<String, Any?>? {
+  val bodyParam = (route.handler as? FunHandler)?.params?.find { it.p.kind != INSTANCE && it.source == null && it.cls.java.packageName != "klite" }?.p
+  val requestBody = annotation?.toNonEmptyValues() ?: HashMap()
+  if (annotation != null && annotation.content.isNotEmpty())
+    requestBody["content"] = annotation.content.associate {
+      val content = it.toNonEmptyValues { it.name != "mediaType" }
+      if (it.schema.implementation != Void::class.java) content["schema"] = it.schema.implementation.createType().toJsonSchema()
+      else if (it.array.schema.implementation != Void::class.java) content["schema"] = Array::class.createType(arguments = listOf(KTypeProjection(null, it.array.schema.implementation.createType()))).toJsonSchema()
+      it.mediaType to content
+    }
+  if (bodyParam != null) requestBody.putIfAbsent("content", bodyParam.type.toJsonContent())
+  if (requestBody.isEmpty()) return null
+  requestBody.putIfAbsent("required", bodyParam == null || !bodyParam.isOptional)
+  return requestBody
+}
+
+private fun toResponsesByCode(route: Route, op: Operation?, returnType: KType?): Map<StatusCode, Any?> {
+  val responses = LinkedHashMap<StatusCode, Any?>()
+  if (returnType?.classifier == Unit::class) responses[NoContent] = mapOf("description" to "No content")
+  else if (op?.responses?.isEmpty() != false) responses[OK] = mapOfNotNull("description" to "OK", "content" to returnType?.toJsonContent(response = true))
+  (route.findAnnotations<ApiResponse>() + (op?.responses ?: emptyArray())).forEach {
+    responses[StatusCode(it.responseCode.toInt())] = it.toNonEmptyValues { it.name != "responseCode" }
+  }
+  return responses
+}
+
+private fun KType.toJsonContent(response: Boolean = false) = mapOf(MimeTypes.json to mapOf("schema" to toJsonSchema(response)))
+
+private fun List<SecurityRequirement>.toSecurity() = map { mapOf(it.name to it.scopes.toList()) }.takeIf { it.isNotEmpty() }
+
+internal fun <T: Annotation> T.toNonEmptyValues(filter: (KProperty1<T, *>) -> Boolean = { true }): MutableMap<String, Any?> = HashMap<String, Any?>().also { map ->
+  publicProperties.filter(filter).forEach { p ->
+    when(val v = p.valueOf(this)) {
+      "", false, 0, Int.MAX_VALUE, Int.MIN_VALUE, 0.0, Void::class.java, AccessMode.AUTO, RequiredMode.AUTO, AdditionalPropertiesValue.USE_ADDITIONAL_PROPERTIES_ANNOTATION -> null
+      is Enum<*> -> v.takeIf { v.name != "DEFAULT" && v.name != "AUTO" }
+      is Annotation -> v.toNonEmptyValues().takeIf { it.isNotEmpty() }
+      is Array<*> -> v.map { (it as? Annotation)?.toNonEmptyValues() ?: it }.takeIf { it.isNotEmpty() }
+      else -> v
+    }?.let { map[p.name] = it }
+  }}