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+unsubscr...@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.
