search

tomtom-international / configuration-service

An easy-to-use, lightweight Jata REST service to store and retrieve configuration data devices (or applications).
Apache License 2.0
7 stars 4 forks source link

add swagger support #2

Open FedorRomanov opened 7 years ago

FedorRomanov commented 7 years ago

Swagger, a tool for representation of RESTful API, can be added to configuration-service. It will allow to test configuration-service from pretty looking html gui and expose documentation to the clients.

rijnb commented 7 years ago

Indeed possible. But that's really why I've added rather extensive examples in the README.md file, so developers would get the hang of it. By the way, did you notice you get the full help text if you call GET / (the root node), as HTML? (The README does not document all calls, such as /version, /status and /.)

FedorRomanov commented 7 years ago

Yes, README.md is quite detailed and have well-described examples. However, the beauty of swagger that it sustains live html documentation - it is generated from swagger annotations during build time. So the docs will never gets outdated(as it usually happens after a while).

Once I peeked into RootResource.java, I've discovered String getHelpHTML() service. As I mentioned in another issue describing helper services(health check, displaying version, displaying help) should be mentioned in main README.md

rijnb commented 7 years ago

Good point. At the very least the README must be complete in that sense. I'll contact you later about the Swagger stuff (which funnily enough I introduced at our company myself years ago...).

rijnb commented 7 years ago

Marked as an enhancement.