Route listings and OpenAPI specs

[v79]

Things which need specs:

• the router itself
• groups
• routes
• schemas (request and response classes)
• authentication handlers

[v79]

Could I do this through an annotation on the route?

@APISpec(Spec("Get person by ID", "Returns a person for the given ID, or an error")
get("/person/{id}", controller::getPerson)

In cantilever I did this through extension functions on the route declaration:

get("/person/{id}", controller::getPerson).spec(Spec("Get person by ID", "Returns a person for the given ID, or an error")

[v79]

The OpenAPI Schema object yaml generation will be most complicated. I will likely need to use runtime reflection, or a ksp plugin at compile time. I'd want to be able to annotate any data class with @APISchema. Google Gemini seems to suggest it's possible...

[v79]

I have been experimenting with KSP annotation processors to see if I can get the OpenAPI schema specifications for Request and Response objects.

KSP cannot analyse the put("/person") { request: Request<Person> -> Response.OK("Created person") } trailing lambda way of declaring routes.

But it can be made with the named function mechanism: put("/person", ::createNewPerson) if I add an annotation to the function, e.g. @OpenAPIRoute fun createNewPerson(request: Request<Person>) : Response<String> {...}.

I think this is an acceptable compromise - if you want the OpenAPI specification yaml file to include data about the classes for requests and responses, then you have to use the named function mechanism.

Having proven that this works, I need to seriously think about how to make this useful.

KSP wants to create new Kotlin sources files in a generated folder, not nice yaml files in src/main/resources.

[v79]

https://www.kodeco.com/33148161-write-a-symbol-processor-with-kotlin-symbol-processing - useful article including validating the use of annotations. E.g. could require that a class is marked as Serializable?

[v79]

With an OpenAPIRoute annotation on controller functions, this would be a good place to add summary and description properties.

[v79]

KSP and compile-time processing cannot build the entire API schema:

• only annotated controller routes can be found at compile time - lambdas will not be. But at run time we can list all the routes. So I'll need to merge the run-time list with the compile-time schema information at run-time
• I can get the authentication security schema stuff at runtime, though there may be value in a compile-time annotation too?
• I can get groups (as "tags") at run-time.
• I can get the request/response content types at runtime.