annotation for OpenAPI parameter value examples

ghik · ghik · commit 06e9f379be0b · 2018-09-19T15:52:10.000+02:00
diff --git a/commons-annotations/src/main/scala/com/avsystem/commons/meta/metaAnnotations.scala b/commons-annotations/src/main/scala/com/avsystem/commons/meta/metaAnnotations.scala
@@ -189,8 +189,24 @@ trait MetadataParamStrategy extends StaticAnnotation
   * method or real parameter matches a metadata parameter. For example, if an implicit for `@infer` parameter cannot be
   * found, you will only know about it *after* the metadata materializing macro has already been expanded.
   * This behaviour can be changed with [[checked]] annotation.
-  */
+  *
+  * The `@infer` annotation may also be used on a parameter of an annotation reified with [[reifyAnnot]] or
+  * [[reifyEncodedAnnot]] in order to simulate implicit parameter. This is a workaround for the fact that Scala
+  * annotations cannot accept multiple parameter lists. In such situation, `infer.value` should be used as default
+  * value of "implicit" annotation parameter:
+  *
+  * {{{
+  *   class valueWithCodec[T](value: T, @infer codec: GenCodec[T] = infer.value)
+  *     extends scala.annotation.StaticAnnotation
+  * }}}
+  **/
 final class infer extends MetadataParamStrategy
+object infer {
+  /**
+    * Can be used as default value of `@infer` annotation parameters.
+    */
+  def value[T]: T = macro macros.misc.WhiteMiscMacros.inferValue
+}
 
 /**
   * `@adtParamMetadata` applied on metadata parameter of metadata class for case class or object indicates that
diff --git a/commons-core/src/main/scala/com/avsystem/commons/rest/openapi/OpenApi.scala b/commons-core/src/main/scala/com/avsystem/commons/rest/openapi/OpenApi.scala
@@ -428,7 +428,7 @@ object Style extends AbstractValueEnumCompanion[Style] {
   */
 case class MediaType(
   @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 encoding: Map[String, Encoding] = Map.empty
 )
diff --git a/commons-core/src/main/scala/com/avsystem/commons/rest/openapi/OpenApiMetadata.scala b/commons-core/src/main/scala/com/avsystem/commons/rest/openapi/OpenApiMetadata.scala
@@ -1,7 +1,8 @@
 package com.avsystem.commons
 package rest.openapi
 
-import com.avsystem.commons.meta.{multi, reifyAnnot, _}
+import com.avsystem.commons.meta._
+import com.avsystem.commons.rest.openapi.adjusters._
 import com.avsystem.commons.rest.{Header => HeaderAnnot, _}
 import com.avsystem.commons.rpc._
 import com.avsystem.commons.serialization.{transientDefault, whenAbsent}
diff --git a/commons-core/src/main/scala/com/avsystem/commons/rest/openapi/RestSchema.scala b/commons-core/src/main/scala/com/avsystem/commons/rest/openapi/RestSchema.scala
@@ -5,6 +5,7 @@ import java.util.UUID
 
 import com.avsystem.commons.misc.{NamedEnum, NamedEnumCompanion, Timestamp}
 import com.avsystem.commons.rest.HttpBody
+import com.avsystem.commons.rest.openapi.adjusters.SchemaAdjuster
 
 import scala.annotation.implicitNotFound
 
diff --git a/commons-core/src/main/scala/com/avsystem/commons/rest/openapi/RestStructure.scala b/commons-core/src/main/scala/com/avsystem/commons/rest/openapi/RestStructure.scala
@@ -5,6 +5,7 @@ import com.avsystem.commons.annotation.positioned
 import com.avsystem.commons.meta._
 import com.avsystem.commons.misc.ValueOf
 import com.avsystem.commons.rest.JsonValue
+import com.avsystem.commons.rest.openapi.adjusters.SchemaAdjuster
 import com.avsystem.commons.serialization._
 
 sealed trait RestStructure[T] extends TypedMetadata[T] {
diff --git a/commons-core/src/main/scala/com/avsystem/commons/rest/openapi/adjusters/Adjuster.scala b/commons-core/src/main/scala/com/avsystem/commons/rest/openapi/adjusters/Adjuster.scala
@@ -1,7 +1,11 @@
 package com.avsystem.commons
-package rest.openapi
+package rest.openapi.adjusters
 
 import com.avsystem.commons.annotation.NotInheritedFromSealedTypes
+import com.avsystem.commons.meta.infer
+import com.avsystem.commons.rest.JsonValue
+import com.avsystem.commons.rest.openapi.{Operation, Parameter, RefOr, RestSchema, RestStructure, Schema}
+import com.avsystem.commons.rpc.AsRaw
 
 import scala.annotation.StaticAnnotation
 
@@ -77,3 +81,11 @@ class description(desc: String) extends SchemaAdjuster with ParameterAdjuster wi
   def adjustParameter(parameter: Parameter): Parameter = parameter.copy(description = desc)
   def adjustOperation(operation: Operation): Operation = operation.copy(description = desc)
 }
+
+/**
+  * Adds example to [[Parameter]] object generated for REST method parameter annotated with this annotation.
+  */
+class example[+T](value: T, @infer asJson: AsRaw[JsonValue, T] = infer.value) extends ParameterAdjuster {
+  def adjustParameter(parameter: Parameter): Parameter =
+    parameter.copy(example = asJson.asRaw(value))
+}
diff --git a/commons-core/src/test/scala/com/avsystem/commons/rest/RestTestApi.scala b/commons-core/src/test/scala/com/avsystem/commons/rest/RestTestApi.scala
@@ -1,7 +1,7 @@
 package com.avsystem.commons
 package rest
 
-import com.avsystem.commons.rest.openapi.description
+import com.avsystem.commons.rest.openapi.adjusters.{description, example}
 import com.avsystem.commons.serialization.{flatten, whenAbsent}
 
 sealed trait BaseEntity
@@ -56,7 +56,7 @@ trait RestTestApi {
   def prefix(
     p0: String,
     @Header("X-H0") h0: String,
-    @Query q0: String
+    @Query @example("q0example") q0: String
   ): RestTestSubApi
 
   def complexParams(
diff --git a/commons-core/src/test/scala/com/avsystem/commons/rest/openapi/OpenApiGenerationTest.scala b/commons-core/src/test/scala/com/avsystem/commons/rest/openapi/OpenApiGenerationTest.scala
@@ -57,7 +57,8 @@ class OpenApiGenerationTest extends FunSuite {
         |            "required": true,
         |            "schema": {
         |              "type": "string"
-        |            }
+        |            },
+        |            "example": "q0example"
         |          },
         |          {
         |            "name": "p1",
diff --git a/commons-core/src/test/scala/com/avsystem/commons/rest/openapi/RestSchemaTest.scala b/commons-core/src/test/scala/com/avsystem/commons/rest/openapi/RestSchemaTest.scala
@@ -2,6 +2,7 @@ package com.avsystem.commons
 package rest.openapi
 
 import com.avsystem.commons.rest.RestDataCompanion
+import com.avsystem.commons.rest.openapi.adjusters.description
 import com.avsystem.commons.serialization.json.JsonStringOutput
 import com.avsystem.commons.serialization.{GenCodec, name, transparent}
 import org.scalatest.FunSuite
diff --git a/commons-macros/src/main/scala/com/avsystem/commons/macros/MacroCommons.scala b/commons-macros/src/main/scala/com/avsystem/commons/macros/MacroCommons.scala
@@ -13,7 +13,8 @@ trait MacroCommons { bundle =>
 
   import c.universe._
 
-  import scala.reflect.{ClassTag, classTag}
+  type ClassTag[T] = scala.reflect.ClassTag[T]
+  final def classTag[T: ClassTag]: ClassTag[T] = scala.reflect.classTag[T]
 
   final val ScalaPkg = q"_root_.scala"
   final val JavaLangPkg = q"_root_.java.lang"
@@ -44,9 +45,11 @@ trait MacroCommons { bundle =>
   final val ImplicitsObj = q"$CommonsPkg.misc.Implicits"
   final val AnnotationAggregateType = getType(tq"$CommonsPkg.annotation.AnnotationAggregate")
   final val DefaultsToNameAT = getType(tq"$CommonsPkg.annotation.defaultsToName")
+  final val InferAT: Type = getType(tq"$CommonsPkg.meta.infer")
   final val NotInheritedFromSealedTypes = getType(tq"$CommonsPkg.annotation.NotInheritedFromSealedTypes")
   final val SeqCompanionSym = typeOf[scala.collection.Seq.type].termSymbol
   final val PositionedAT = getType(tq"$CommonsPkg.annotation.positioned")
+  final val AnnotationType = getType(tq"$ScalaPkg.annotation.Annotation")
   final val ImplicitNotFoundAT = getType(tq"$ScalaPkg.annotation.implicitNotFound")
 
   final val NothingTpe: Type = typeOf[Nothing]
@@ -104,13 +107,17 @@ trait MacroCommons { bundle =>
     lazy val tree: Tree = annotTree match {
       case Apply(constr@Select(New(tpt), termNames.CONSTRUCTOR), args) =>
         val clsTpe = tpt.tpe
-        val params = primaryConstructorOf(clsTpe).typeSignature.paramLists.head
+        val params = primaryConstructorOf(clsTpe).typeSignatureIn(clsTpe).paramLists.head
 
         val newArgs = (args zip params) map {
           case (arg, param) if param.asTerm.isParamWithDefault && arg.symbol != null &&
-            arg.symbol.isSynthetic && arg.symbol.name.decodedName.toString.contains("$default$") &&
-            findAnnotation(param, DefaultsToNameAT).nonEmpty =>
-            q"${subject.name.decodedName.toString}"
+            arg.symbol.isSynthetic && arg.symbol.name.decodedName.toString.contains("$default$") =>
+            if (findAnnotation(param, DefaultsToNameAT).nonEmpty)
+              q"${subject.name.decodedName.toString}"
+            else if (findAnnotation(param, InferAT).nonEmpty)
+              q"$ImplicitsObj.infer[${param.typeSignature}](${StringLiteral("", arg.pos)})"
+            else
+              arg
           case (arg, _) => arg
         }
 
diff --git a/commons-macros/src/main/scala/com/avsystem/commons/macros/meta/MacroMetadatas.scala b/commons-macros/src/main/scala/com/avsystem/commons/macros/meta/MacroMetadatas.scala
@@ -16,7 +16,6 @@ trait MacroMetadatas extends MacroSymbols {
   val ReifyAnnotAT: Type = getType(tq"$MetaPackage.reifyAnnot")
   val ReifyEncodedAnnotAT: Type = getType(tq"$MetaPackage.reifyEncodedAnnot[_]")
   val IsAnnotatedAT: Type = getType(tq"$MetaPackage.isAnnotated[_]")
-  val InferAT: Type = getType(tq"$MetaPackage.infer")
   val ReifyNameAT: Type = getType(tq"$MetaPackage.reifyName")
   val ReifyPositionAT: Type = getType(tq"$MetaPackage.reifyPosition")
   val ReifyFlagsAT: Type = getType(tq"$MetaPackage.reifyFlags")
diff --git a/commons-macros/src/main/scala/com/avsystem/commons/macros/misc/MiscMacros.scala b/commons-macros/src/main/scala/com/avsystem/commons/macros/misc/MiscMacros.scala
@@ -353,12 +353,12 @@ class WhiteMiscMacros(ctx: whitebox.Context) extends AbstractMacroCommons(ctx) {
   import c.universe._
 
   val WhenAbsentAT: Type = getType(tq"$CommonsPkg.serialization.whenAbsent[_]")
-  val DefaultValueMethodSuffix: Regex = """(.*)\$default\$(\d+)$""".r
+  val DefaultValueMethodName: Regex = """(.*)\$default\$(\d+)$""".r
 
   object DefaultValueMethod {
     def unapply(s: Symbol): Option[Symbol] = s match {
       case ms: MethodSymbol if ms.isSynthetic => ms.name.encodedName.toString match {
-        case DefaultValueMethodSuffix(name, idx) =>
+        case DefaultValueMethodName(name, idx) =>
           val actualMethodName = TermName(name).decodedName
           val paramIndex = idx.toInt - 1
           val ownerMethod = actualMethodName match {
@@ -386,4 +386,15 @@ class WhiteMiscMacros(ctx: whitebox.Context) extends AbstractMacroCommons(ctx) {
       abort(s"no @whenAbsent annotation found on $param of ${param.owner}")
     }
   }
+
+  def inferValue: Tree = {
+    val param = c.internal.enclosingOwner match {
+      case DefaultValueMethod(p) => p
+      case p => p
+    }
+    if (param.owner.owner.asType.toType <:< AnnotationType && findAnnotation(param, InferAT).nonEmpty)
+      q"""throw new $ScalaPkg.NotImplementedError("infer.value")"""
+    else
+      abort(s"infer.value can be only used as default value of @infer annotation parameters")
+  }
 }

Original file line number	Diff line number	Diff line change
`@@ -428,7 +428,7 @@ object Style extends AbstractValueEnumCompanion[Style] {`
`428`	`428`	`*/`
`429`	`429`	`case class MediaType(`
`430`	`430`	`@td schema: OptArg[RefOr[Schema]] = OptArg.Empty,`
`431`		`- @td example: OptArg[String] = OptArg.Empty, //TODO other values than strings`
	`431`	`+ @td example: OptArg[JsonValue] = OptArg.Empty,`
`432`	`432`	`@td examples: Map[String, RefOr[Example]] = Map.empty,`
`433`	`433`	`@td encoding: Map[String, Encoding] = Map.empty`
`434`	`434`	`)`