A way of generating/baking awesome REST docs

HI all!

First of all - sorry if this is not the place for discussing such things as "ideas" for new plugins/libraries - and sorry for the length of this post O.o

From my work we've lately had the need of getting started to port/move our internal REST api to a public one - and in that case we started looking for "proper" REST documentation tools.

We had a few must-have requirements in order to start searching:

• Generated automatically (integration to our CI)
  
• Some docs that feels nice to read through
• Open source source
• The least work possible for ourselves
• Easy to maintain

Nice-to haves:

• Exist in our version control (inside our source files - then also work as "documentation" whenever reading the code.
• Automatically generate "examples" in different languages, Python, Ruby, PHP, JavaScript, Curl etc. for
• A "try me" functionality in the docs, so instead of using time on documentation how eg. a response looks, the reader can fire off a "try me" live to our server and see the response
• Have in mind this is by developers, for developers - but not necessarily anyone that knows our software at all.
• Output is simple html/js files that can just be thrown at a webserver like a no-brainer

So we started by looking at what other Companies did, and we found a few (what we think) awesome docs:

• Economic (ERP system) - http://restdocs.e-conomic.com
• Made w/ https://github.com/tripit/slate
• Pipedrive (CRM system) - https://developers.pipedrive.com/v1
• Made w/ https://github.com/mashery/iodocs
• QuickPay (PSP) - http://tech.quickpay.net/api/services
• Made with ???
• Any API made with "Swagger" - http://petstore.swagger.io
• Made w/ http://swagger.io

But none of these are actually able to be generated from within our CakePHP src in a nice way - the closest we got was with the package swagger-php - but still it's not really "DRY"... 

So all of this (and my laziness) got me thinking - is there a smarter way than just starting to annotate like a crazy - to start extrating this kind of code from our src, and it indeed seems reasonable to do it.

So first of all - does anyone have any super-awesome toolset, that we just totally missed - and second, what would be the most awesome docs tool you could imagine?

I'm wrapping my head around something that would pair up nicely with the idea behind Crud - it might not get you all the way by doing nothing, but it's damn close.

Also, if one were to start up a plugin for generating docs for CakePHP projects - should it be independent of other projects like Swagger, IODocs and Slate? I guess we have 3 options:

A) Our own

B) Using one specific provider (eg. Swagger)

C) Using adapters for 3rd party providers - it's more or less the same kind of info we all want as output, it's just a matter of syntax and formalities in regard to generate those docs, so it's definitely possible to add a layer of abstraction with adapters to the providers people want to use.

Last thing - does this have any interest at all - or are we the single company that has this "issue"? :-)

Thanks for reading!

--
Like Us on FaceBook https://www.facebook.com/CakePHP
Find us on Twitter http://twitter.com/CakePHP

---
You received this message because you are subscribed to the Google Groups "CakePHP" group.
To unsubscribe from this group and stop receiving emails from it, send an email to cake-php+unsubscribe@googlegroups.com.
To post to this group, send email to cake-php@googlegroups.com.
Visit this group at http://groups.google.com/group/cake-php.
For more options, visit https://groups.google.com/d/optout.