osiam
Generate documentation for OSIAMs public REST-APIs
We fall a little short on the documentation side. Maybe it is a good idea to use a tool like Swagger to create interactive documentation for our REST-APIs, Swagger does not seem to support Spring MVC but I found the alternative Springfox which provides the same service. Maybe we should take a look at it.
That being said, I'm not a fan of automatically generated documentation, it tends to be bad most of the time. None the less I think we could at least for the time being benefit from it.
Any thoughts?
Where would we host that docs? Or do you suggest introducing a build-task for creating them locally? I guess we would need a new (gh pages based?) website first.
Anyway, I am definitely in favor of evaluating springfox. The focus on spring seems just perfect. And I think we will gain some value, even when the documentation that is produced by a tool is not ideal.
First: I'm in favor that we experiment with automatically generated API documentation.
But for me it seems, that there are multiple issues to solve. How do we integrate this with the other docs? How are we supposed to shape the process that turns .java files into HTML documents that can then be integrated into the other docs? What does the output of Springfox look like (I couldn't find a full example on this on their website)?
It would be nice if someone could make up an example.
Does anyone know spring-restdocs? I skimmed over the README and the linked slides, and I think it addresses the concerns we have about swagger. What do you think?
spring-restdocs does indeed look promising. I support @sputnik27's suggestion to give it a try.
Would be really cool, if somebody could show an example or PoC. @sputnik27, I'm looking in your direction :)