Open v79 opened 3 months ago
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")
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...
I have been experimenting with KSP annotation processors to see if I can get the OpenAPI schema specifications for Request
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.
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?
With an OpenAPIRoute
annotation on controller functions, this would be a good place to add summary and description properties.
KSP and compile-time processing cannot build the entire API schema:
Things which need specs: