search

joffrey-bion / livedoc

A not-so-annotation-based documentation generator for REST and websocket services
MIT License
4 stars 2 forks source link

Add OpenAPI spec file export #58

Open joffrey-bion opened 6 years ago

joffrey-bion commented 6 years ago

Maybe we could add a feature to export the doc as a yml/json Swagger file. This way, we could benefit from Livedoc annotations + Swagger code generation for REST APIs.

Swagger lacks websocket support, so we should find a way to filter all websocket information to generate the swagger file.

ST-DDT commented 6 years ago

Good idea, but keep it as an optional module. Because there a quite a lot of libraries worth generating.

ST-DDT commented 6 years ago

Do you have a preferred OpenAPI API/Model bundle? Something like https://github.com/swagger-api/swagger-core/tree/master/modules/swagger-models ? I thought about implementing this feature for you. (Might as well add an PDF export)

joffrey-bion commented 6 years ago

For now, I had only thought about the resulting file (yaml or json), which would need to match the OpenAPI spec. The way to get there most likely implies using a Java representation indeed, but I had not looked anything up so far and I have no constraints on it. I am not aware of other implementations than the swagger one, it seems perfectly fine IMO to reuse the swagger-core model.

Thanks a lot for wanting to contribute! Sorry for not being active lately, I have a lot of personal stuff going on, and not much room for late night coding. I appreciate your help.

As you probably understand, this feature would be most interesting as part of a build-plugin (maven or gradle), but even as standalone, the code to convert from a Livedoc to an OpenAPI object would be a good start. Then, the YAML or JSON export could be provided as another endpoint than /jsondoc, before being available as an option in the gradle or maven plugin.