Merge pull request #86 from AVSystem/json-defaults

Arbitrary JSON default values for OpenAPI

Author: ghik

commons-annotations/src/main/scala/com/avsystem/commons/meta/metaAnnotations.scala

@@ -225,6 +225,16 @@ final class adtCaseMetadata extends MetadataParamStrategy
   */
 final class reifyAnnot extends MetadataParamStrategy
 
+/**
+  * Similar to [[reifyAnnot]] but the annotation is encoded into some raw type (which is the type of the parameter).
+  * Because the type of the parameter is now the raw type, annotation type must be given as type parameter of
+  * [[reifyEncodedAnnot]].
+  *
+  * Encoding is done by searching and using implicit instance of `AsRaw[ParameterType,AnnotationType]`.
+  * Arity annotations apply in the same way as for [[reifyAnnot]].
+  */
+final class reifyEncodedAnnot[T <: StaticAnnotation] extends MetadataParamStrategy
+
 /**
   * Metadata parameter typed as `Boolean` can be annotated with `@isAnnotated[SomeAnnotation]`. Boolean value will then
   * hold information about whether RPC trait, method or parameter for which metadata is materialized is annotated with

commons-annotations/src/main/scala/com/avsystem/commons/serialization/whenAbsent.scala

@@ -28,3 +28,17 @@ import scala.annotation.StaticAnnotation
 class whenAbsent[+T](v: => T) extends StaticAnnotation {
   def value: T = v
 }
+object whenAbsent {
+  /**
+    * If you want your parameter to have _both_ a `@whenAbsent` annotation and a Scala-level default value, you can
+    * use this macro to avoid writing the default value twice:
+    *
+    * {{{
+    *   case class Record(@whenAbsent(0) i: Int = whenAbsent.value)
+    * }}}
+    *
+    * This is useful when you want the default value to be collectible by macros (e.g. `OpenApiMetadata` for REST).
+    * which is possible only with default value in annotation.
+    */
+  def value[T]: T = macro macros.misc.WhiteMiscMacros.whenAbsentValue
+}

commons-core/src/main/scala/com/avsystem/commons/SharedExtensions.scala

@@ -63,6 +63,9 @@ object SharedExtensions extends SharedExtensions {
       */
     def |>[B](f: A => B): B = f(a)
 
+    def applyIf[A0 >: A](predicate: A => Boolean)(f: A => A0): A0 =
+      if (predicate(a)) f(a) else a
+
     /**
       * Explicit syntax to discard the value of a side-effecting expression.
       * Useful when `-Ywarn-value-discard` compiler option is enabled.

commons-core/src/main/scala/com/avsystem/commons/meta/AdtMetadataCompanion.scala

@@ -7,5 +7,5 @@ import com.avsystem.commons.misc.MacroGenerated
 trait AdtMetadataCompanion[M[_]] extends MetadataCompanion[M] {
   def materialize[T]: M[T] = macro AdtMetadataMacros.materialize[T]
 
-  implicit def materializeMacroGenerated[T]: MacroGenerated[M[T]] = macro AdtMetadataMacros.materializeMacroGenerated[T]
+  implicit def materializeMacroGenerated[C, T]: MacroGenerated[C, M[T]] = macro AdtMetadataMacros.materializeMacroGenerated[T]
 }

commons-core/src/main/scala/com/avsystem/commons/misc/MacroGenerated.scala

@@ -1,8 +1,23 @@
 package com.avsystem.commons
 package misc
 
-class MacroGenerated[T](val forCompanion: Any => T)
+/**
+  * Wrapper class for macro-generated typeclasses. Usually, a typeclass is wrapped in `MacroGenerated` when
+  * it's accepted as implicit super constructor parameter of some base class for companion objects of
+  * types for which the typeclass is being generated.
+  * Example: [[com.avsystem.commons.serialization.HasGenCodec HasGenCodec]], which is a base class for
+  * companion objects of classes that want [[com.avsystem.commons.serialization.GenCodec GenCodec]] to be
+  * macro-generated for them.
+  *
+  * Instead of materializing the type class instance directly, a function from some base companion type `C` is
+  * materialized. To obtain the actual typeclass instance, companion object must be passed as this function's
+  * argument. This serves two purposes:
+  *
+  * - contents of `C` will be wildcard-imported into macro-materialization, allowing injection of additional implicits
+  * - working around too strict Scala validation of super constructor arguments: https://github.com/scala/bug/issues/7666
+  */
+class MacroGenerated[C, T](val forCompanion: C => T) extends AnyVal
 object MacroGenerated {
-  def apply[T](instance: => T): MacroGenerated[T] =
-    new MacroGenerated[T](_ => instance)
+  def apply[C, T](instance: => T): MacroGenerated[C, T] =
+    new MacroGenerated[C, T](_ => instance)
 }

commons-core/src/main/scala/com/avsystem/commons/rest/DefaultRestApiCompanion.scala

@@ -20,9 +20,10 @@ import com.avsystem.commons.serialization.{GenCodec, GenKeyCodec, HasGenCodec}
   *   object User extends RestDataCompanion[User]
   * }}}
   */
-abstract class RestDataCompanion[T](
-  implicit macroRestStructure: MacroGenerated[RestStructure[T]], macroCodec: MacroGenerated[GenCodec[T]]
-) extends HasGenCodec[T] {
+abstract class RestDataCompanion[T](implicit
+  macroRestStructure: MacroGenerated[DefaultRestImplicits, RestStructure[T]],
+  macroCodec: MacroGenerated[Any, GenCodec[T]]
+) extends HasGenCodec[T] with DefaultRestImplicits {
   implicit lazy val restStructure: RestStructure[T] = macroRestStructure.forCompanion(this)
   implicit lazy val restSchema: RestSchema[T] = restStructure.standaloneSchema // lazy on restStructure
 }
@@ -46,7 +47,7 @@ trait OpenApiFullInstances[Real] extends FullInstances[Real] {
   def openapiMetadata: OpenApiMetadata[Real]
 }
 
-/** @see [[RestApiCompanion]] */
+/** @see [[RestApiCompanion]]*/
 abstract class RestClientApiCompanion[Implicits, Real](protected val implicits: Implicits)(
   implicit inst: RpcMacroInstances[Implicits, ClientInstances, Real]
 ) {
@@ -57,7 +58,7 @@ abstract class RestClientApiCompanion[Implicits, Real](protected val implicits:
     RawRest.fromHandleRequest(handleRequest)
 }
 
-/** @see [[RestApiCompanion]] */
+/** @see [[RestApiCompanion]]*/
 abstract class RestServerApiCompanion[Implicits, Real](protected val implicits: Implicits)(
   implicit inst: RpcMacroInstances[Implicits, ServerInstances, Real]
 ) {
@@ -68,7 +69,7 @@ abstract class RestServerApiCompanion[Implicits, Real](protected val implicits:
     RawRest.asHandleRequest(real)
 }
 
-/** @see [[RestApiCompanion]] */
+/** @see [[RestApiCompanion]]*/
 abstract class RestServerOpenApiCompanion[Implicits, Real](protected val implicits: Implicits)(
   implicit inst: RpcMacroInstances[Implicits, OpenApiServerInstances, Real]
 ) {
@@ -99,7 +100,7 @@ abstract class RestApiCompanion[Implicits, Real](protected val implicits: Implic
     RawRest.asHandleRequest(real)
 }
 
-/** @see [[RestApiCompanion]] */
+/** @see [[RestApiCompanion]]*/
 abstract class RestOpenApiCompanion[Implicits, Real](protected val implicits: Implicits)(
   implicit inst: RpcMacroInstances[Implicits, OpenApiFullInstances, Real]
 ) {

commons-core/src/main/scala/com/avsystem/commons/rest/annotations.scala

@@ -114,7 +114,20 @@ class FormBody extends StaticAnnotation
 class Prefix(val path: String = null) extends RestMethodTag
 
 sealed trait RestParamTag extends RpcTag
-sealed trait NonBodyTag extends RestParamTag
+sealed trait NonBodyTag extends RestParamTag {
+  def isPath: Boolean = this match {
+    case _: Path => true
+    case _ => false
+  }
+  def isHeader: Boolean = this match {
+    case _: Header => true
+    case _ => false
+  }
+  def isQuery: Boolean = this match {
+    case _: Query => true
+    case _ => false
+  }
+}
 sealed trait BodyTag extends RestParamTag
 
 /**

commons-core/src/main/scala/com/avsystem/commons/rest/data.scala

@@ -6,6 +6,7 @@ import com.avsystem.commons.misc.{AbstractValueEnum, AbstractValueEnumCompanion,
 import com.avsystem.commons.rpc._
 import com.avsystem.commons.serialization.GenCodec.ReadFailure
 import com.avsystem.commons.serialization.json.{JsonReader, JsonStringInput, JsonStringOutput}
+import com.avsystem.commons.serialization.{GenCodec, whenAbsent}
 
 import scala.util.control.NoStackTrace
 
@@ -55,6 +56,23 @@ object QueryValue {
   * Wrapped value MUST be a valid JSON.
   */
 case class JsonValue(value: String) extends AnyVal with RestValue
+object JsonValue {
+  // TODO: this is terrible, but GenCodec in general just can't embed arbitrary JSON at this point...
+  private[rest] implicit val codec: GenCodec[JsonValue] =
+    GenCodec.create(
+      {
+        case ji: JsonStringInput => JsonValue(ji.readRawJson())
+        case i => JsonValue(i.readString())
+      },
+      {
+        case (jo: JsonStringOutput, JsonValue(json)) => jo.writeRawJson(json)
+        case (o, JsonValue(json)) => o.writeString(json)
+      }
+    )
+
+  implicit def whenAbsentAsJson[T](implicit valueAsJson: AsRaw[JsonValue, T]): AsRaw[Try[JsonValue], whenAbsent[T]] =
+    AsRaw.create(wa => Try(wa.value).map(valueAsJson.asRaw))
+}
 
 /**
   * Value used to represent HTTP body. Also used as direct encoding of [[Body]] parameters. Types that have

commons-core/src/main/scala/com/avsystem/commons/rest/openapi/OpenApi.scala

@@ -2,6 +2,8 @@ package com.avsystem.commons
 package rest.openapi
 
 import com.avsystem.commons.misc.{AbstractValueEnum, AbstractValueEnumCompanion, EnumCtx}
+import com.avsystem.commons.rest.JsonValue
+import com.avsystem.commons.serialization.json.JsonStringOutput
 import com.avsystem.commons.serialization.{transientDefault => td, _}
 
 /**
@@ -255,8 +257,8 @@ case class Schema(
   @td not: OptArg[RefOr[Schema]] = OptArg.Empty,
   @td discriminator: OptArg[Discriminator] = OptArg.Empty,
 
-  @td enum: List[String] = Nil, //TODO: other values than strings
-  @td default: OptArg[String] = OptArg.Empty //TODO: other values than strings
+  @td enum: List[JsonValue] = Nil,
+  @td default: OptArg[JsonValue] = OptArg.Empty
 ) {
   def unwrapSingleRefAllOf: RefOr[Schema] = allOf match {
     case List(ref: RefOr.Ref) if this == Schema(allOf = List(ref)) => ref
@@ -291,7 +293,7 @@ object Schema extends HasGenCodec[Schema] {
     Schema(`type` = DataType.Object, additionalProperties = properties)
 
   def enumOf(values: List[String]): Schema =
-    Schema(`type` = DataType.String, enum = values)
+    Schema(`type` = DataType.String, enum = values.map(s => JsonValue(JsonStringOutput.write(s))))
 
   def nullable(schema: RefOr[Schema]): Schema =
     schema.rewrapRefToAllOf.copy(nullable = true)
@@ -306,6 +308,9 @@ object Schema extends HasGenCodec[Schema] {
       case RefOr.Value(schema) => schema
       case ref => Schema(allOf = List(ref))
     }
+
+    def withDefaultValue(dv: Opt[Try[JsonValue]]): RefOr[Schema] =
+      dv.collect({ case Success(v) => v }).fold(refOrSchema)(v => RefOr(rewrapRefToAllOf.copy(default = v)))
   }
 }
 
@@ -380,7 +385,7 @@ case class Parameter(
   @td explode: OptArg[Boolean] = OptArg.Empty,
   @td allowReserved: Boolean = false,
   @td schema: OptArg[RefOr[Schema]] = OptArg.Empty,
-  @td example: OptArg[String] = OptArg.Empty, //TODO other values than strings
+  @td example: OptArg[JsonValue] = OptArg.Empty,
   @td examples: Map[String, RefOr[Example]] = Map.empty,
   @td content: OptArg[Entry[String, MediaType]] = OptArg.Empty
 )
@@ -445,7 +450,7 @@ object Encoding extends HasGenCodec[Encoding]
 case class Example(
   @td summary: OptArg[String] = OptArg.Empty,
   @td description: OptArg[String] = OptArg.Empty,
-  @td value: OptArg[String] = OptArg.Empty, //TODO other values than strings
+  @td value: OptArg[JsonValue] = OptArg.Empty,
   @td externalValue: OptArg[String] = OptArg.Empty
 )
 object Example extends HasGenCodec[Example]
@@ -474,7 +479,7 @@ case class Header(
   @td explode: OptArg[Boolean] = OptArg.Empty,
   @td allowReserved: Boolean = false,
   @td schema: OptArg[RefOr[Schema]] = OptArg.Empty,
-  @td example: OptArg[String] = OptArg.Empty, //TODO other values than strings
+  @td example: OptArg[JsonValue] = OptArg.Empty,
   @td examples: Map[String, RefOr[Example]] = Map.empty,
   @td content: OptArg[Entry[String, MediaType]] = OptArg.Empty
 )
@@ -544,8 +549,8 @@ object OAuthFlow extends HasGenCodec[OAuthFlow]
 case class Link(
   @td operationRef: OptArg[String] = OptArg.Empty,
   @td operationId: OptArg[String] = OptArg.Empty,
-  @td parameters: Map[String, String] = Map.empty, //TODO: other values than strings
-  @td requestBody: OptArg[String] = OptArg.Empty, //TODO: other values than strings
+  @td parameters: Map[String, JsonValue] = Map.empty,
+  @td requestBody: OptArg[JsonValue] = OptArg.Empty,
   @td description: OptArg[String] = OptArg.Empty,
   @td server: OptArg[Server] = OptArg.Empty
 )

commons-core/src/main/scala/com/avsystem/commons/rest/openapi/OpenApiMetadata.scala

@@ -12,19 +12,20 @@ import scala.annotation.implicitNotFound
   "${T} extend one of the convenience base companion classes, e.g. DefaultRestApiCompanion")
 @methodTag[RestMethodTag]
 case class OpenApiMetadata[T](
-  @multi @tagged[Prefix](whenUntagged = new Prefix)
+  @multi @rpcMethodMetadata
+  @tagged[Prefix](whenUntagged = new Prefix)
   @paramTag[RestParamTag](defaultTag = new Path)
-  @rpcMethodMetadata
   prefixes: List[OpenApiPrefix[_]],
 
-  @multi @tagged[GET]
+  @multi @rpcMethodMetadata
+  @tagged[GET]
   @paramTag[RestParamTag](defaultTag = new Query)
   @rpcMethodMetadata
   gets: List[OpenApiGetOperation[_]],
 
-  @multi @tagged[BodyMethodTag](whenUntagged = new POST)
+  @multi @rpcMethodMetadata
+  @tagged[BodyMethodTag](whenUntagged = new POST)
   @paramTag[RestParamTag](defaultTag = new BodyField)
-  @rpcMethodMetadata
   bodyMethods: List[OpenApiBodyOperation[_]]
 ) {
   val httpMethods: List[OpenApiOperation[_]] = (gets: List[OpenApiOperation[_]]) ++ bodyMethods
@@ -76,9 +77,7 @@ object OpenApiMetadata extends RpcMetadataCompanion[OpenApiMetadata]
 sealed trait OpenApiMethod[T] extends TypedMetadata[T] {
   @reifyName(useRawName = true) def name: String
   @reifyAnnot def methodTag: RestMethodTag
-  @multi
-  @rpcParamMetadata
-  @tagged[NonBodyTag] def parameters: List[OpenApiParameter[_]]
+  @multi @rpcParamMetadata @tagged[NonBodyTag] def parameters: List[OpenApiParameter[_]]
 
   val pathPattern: String = {
     val pathParts = methodTag.path :: parameters.flatMap {
@@ -109,10 +108,8 @@ case class OpenApiPrefix[T](
 }
 
 sealed trait OpenApiOperation[T] extends OpenApiMethod[T] {
-  @infer
-  @checked def resultType: RestResultType[T]
-  @multi
-  @reifyAnnot def adjusters: List[OperationAdjuster]
+  @infer @checked def resultType: RestResultType[T]
+  @multi @reifyAnnot def adjusters: List[OperationAdjuster]
   def methodTag: HttpMethodTag
   def requestBody(resolver: SchemaResolver): Opt[RefOr[RequestBody]]
 
@@ -151,25 +148,27 @@ case class OpenApiBodyOperation[T](
   def requestBody(resolver: SchemaResolver): Opt[RefOr[RequestBody]] =
     singleBody.map(_.requestBody(resolver).opt).getOrElse {
       if (bodyFields.isEmpty) Opt.Empty else Opt {
-        val schema = Schema(`type` = DataType.Object,
-          properties = bodyFields.iterator.map(p => (p.info.name, p.schema(resolver))).toMap,
-          required = bodyFields.collect { case p if !p.info.hasFallbackValue => p.info.name }
-        )
+        val fields = bodyFields.iterator.map(p => (p.info.name, p.schema(resolver))).toMap
+        val requiredFields = bodyFields.collect { case p if !p.info.hasFallbackValue => p.info.name }
+        val schema = Schema(`type` = DataType.Object, properties = fields, required = requiredFields)
         val mimeType = if (formBody) HttpBody.FormType else HttpBody.JsonType
-        RefOr(RestRequestBody.simpleRequestBody(mimeType, RefOr(schema)))
+        RefOr(RestRequestBody.simpleRequestBody(mimeType, RefOr(schema), requiredFields.nonEmpty))
       }
     }
 }
 
 case class OpenApiParamInfo[T](
   @reifyName(useRawName = true) name: String,
-  @optional @reifyAnnot whenAbsent: Opt[whenAbsent[T]],
+  @optional @reifyEncodedAnnot[whenAbsent[T]] whenAbsent: Opt[Try[JsonValue]],
   @isAnnotated[transientDefault] transientDefault: Boolean,
   @reifyFlags flags: ParamFlags,
   @infer restSchema: RestSchema[T]
 ) extends TypedMetadata[T] {
   val hasFallbackValue: Boolean =
-    whenAbsent.fold(flags.hasDefaultValue)(wa => Try(wa.value).isSuccess)
+    whenAbsent.fold(flags.hasDefaultValue)(_.isSuccess)
+
+  def schema(resolver: SchemaResolver, withDefaultValue: Boolean): RefOr[Schema] =
+    resolver.resolve(restSchema) |> (s => if (withDefaultValue) s.withDefaultValue(whenAbsent) else s)
 }
 
 case class OpenApiParameter[T](
@@ -184,7 +183,11 @@ case class OpenApiParameter[T](
       case _: HeaderAnnot => Location.Header
       case _: Query => Location.Query
     }
-    val param = Parameter(info.name, in, required = !info.hasFallbackValue, schema = resolver.resolve(info.restSchema))
+    val pathParam = in == Location.Path
+    val param = Parameter(info.name, in,
+      required = pathParam || !info.hasFallbackValue,
+      schema = info.schema(resolver, withDefaultValue = !pathParam)
+    )
     RefOr(adjusters.foldRight(param)(_ adjustParameter _))
   }
 }
@@ -194,7 +197,7 @@ case class OpenApiBodyField[T](
   @multi @reifyAnnot schemaAdjusters: List[SchemaAdjuster]
 ) extends TypedMetadata[T] {
   def schema(resolver: SchemaResolver): RefOr[Schema] =
-    SchemaAdjuster.adjustRef(schemaAdjusters, resolver.resolve(info.restSchema))
+    SchemaAdjuster.adjustRef(schemaAdjusters, info.schema(resolver, withDefaultValue = true))
 }
 
 case class OpenApiBody[T](