Isolate the instantiation of an annotation

Question

I have a huge @OpenApi annotation (basically it's documentation of a Javalin/Kotlin endpoint) which occupies a lot of lines:

@OpenApi(
   summary = "",
   description = "Lists all customers",
   path = "customers",
   queryParams =
   // ...........
   // ...........
   // etc
)
override fun handle(context: Context) {
   // body of the REST handler
}

I have to scroll a lot to see the actual handler. Hence, I'd like to isolate it somehow like:

@GetCustomersDoc
override fun handle(context: Context) {
   // body of the REST handler
}

I'm OK with other solutions that make the documentation go elsewhere.

This would make the code cleaner and the docs segregated.

HI! Just wanted to check if there was some problem with what I proposed and if I can clarify anything? — Enselic, Oct 07 '19 at 07:17

score 1 · Answer 1 · answered Sep 30 '19 at 10:46

1

You could define separate Annotations:

annotation class MyOwnApi(
    val openApi: OpenApi = OpenApi(
          summary = "",
          description = "Lists all customers",
          path = "customers",
          queryParams =
          // ...........
          // ...........
          // etc
        )
)

annotation class UserOpenApi(
        val openApi: OpenApi = OpenApi(
              summary = "Something",
              description = "Lists all users",
              // ...........
              // ...........
              // etc
            )
    )

Pros:

Code separation
Reusable annontation classes
You could even make a builder class and test it

Cons:

Confusing
Annotations can't inherit, extend classes or implement Interfaces
May not be possible to implement or require complex code changes, if the classes/objects are checked for @OpenApi directly. In this case, you would need another reflective search to pull the annotation from a field!

answered Sep 30 '19 at 10:46

Neo

1,869
1
7
20

I think you commented the wrong post? Your post gives a good solution too, but the scrolling problem is still there, because you would need to scroll down to see the helping method – Neo Oct 07 '19 at 07:14
Misplaced comment deleted. No need to scroll btw, one just use the *Go To* -> *Definition* functionality of Android Studio. – Enselic Oct 07 '19 at 07:17
how to use that new annotation? – Luís Soares Oct 08 '19 at 10:18
@LuísSoares Annotate your class as usual `@MyOwnApi class Clazz { ... }` – Neo Oct 08 '19 at 10:23

Enselic · Accepted Answer · 2019-10-07T07:22:00.377

Ok so what you want is the @OpenApi docs to be separated from the REST handler code. You can do that by moving away the implementation rather than moving away the annotation.

So in your current file with all the @OpenApi annotations mixed with REST handler code, you call helper functions, like this:

@OpenApi(
   summary = "",
   description = "Lists all customers",
   path = "customers",
   queryParams =
   // ...........
   // ...........
   // etc
)
override fun handle(context: Context) {
   handleGetCustomers(context)
}

and then you put - either in the top of that file or in another file for even more segregation - all REST handlers, which allows you to scroll among them without the noise of @OpenApi annotations:

// Collected at the top of the file, or in a separate file
fun handleGetCustomers(context: Context) {
    // body of the REST handler
}

Then you can easily scroll among your REST handler code without being bothered by @OpenApi noise.

Note that you should use the Go To -> Definition functionality of Android Studio to avoid having to scroll to handleGetCustomers().

Isolate the instantiation of an annotation

2 Answers2