Generate REST API documentation from the code

[jean-morissette]

Generate REST API documentation from the code, something similar to Swagger JAX-RS extension, but without all their annotations (they have just too many), which is possible in Ceylon, thanks to its great metaprogramming, reified generics and its support of named, optional and default arguments).

It could be another module that inspects the app and generates an HTML report. Something that could be done in a continuous integration server, for example.

[bjansen]

Example here: https://github.com/swagger-api/swagger-core

[fwgreen]

I wonder if ceylon-doc could be used for this some how?

[jvasileff]

@lucaswerkmeister's idea (eclipse-archived/ceylon#2083) would work for this. See eclipse-archived/ceylon#2083 (comment)

[bjansen]

I don't know if this solution would be flexible enough. Also, it would imply adding more annotations to the program, and those annotations would only be there to generate the doc. They are useless at runtime, and they are useless when you are reading the code.

In my opinion, it would add "noise" in declarations, especially if we have to give those annotations a lot of redundant information. ceylon-doc will never be aware of the route() annotation, so this means we would have to specify the path, methods etc a second time in another annotation, just to generate documentation.

[lucaswerkmeister]

No, route would be a “doc annotation” (in addition to being an annotation for your framework), so ceylon doc would be aware of it and generate documentation from it.

[bjansen]

Ah, then I need to read the full thread to understand how that would work :D

[bjansen]

If we go the ceylon-doc way, this feature won't be implemented before 1.3.

Moreover, while it is "easy" to query the metamodel and generate a report for annotated controllers, I'm pretty sure it won't be possible for get(), post() etc. without having to actually run the application, or perhaps parse the source code...

[bjansen]

Here's what I was able to do with the metamodel:

Archive.zip

I can't document routes defined via get(), post() etc., and I can't document HTTP response codes other than the ones automatically returned by the framework. I may need extra annotations to be able to do that.