auto generate RAML documentation

[timothycrosley]

It would be useful if hug could optionally auto generate RAML style documentation, in addition to it's default json documentation format. For more information on the spec see: http://raml.org/

[mvillis]

equally, auto generation of a swagger (openapi) spec would be useful.

[wing328]

@mvillis I opened #198 for tracking.

[jacobsvante]

RAML is awesome. Could make for a killer combo 😀

[vltr]

Sorry if this isn't the right place (or time) to share my comment, but finding myself in a middle of a research for what (technologies) to use in a new project, it's getting harder and harder to select any that seeks to be "peaceful" around formats. Let me be more specific, or at least you'll try to.
I came across hug by a reference in the marshmallow wiki - great project by the way! It's interesting to me any auto-generated documents, but like as many other developers I was searching for some standard spec that could be "simply added" to my project so third parties could test and explore the API for future integrations - being the OpenAPI spec one of personal interest. Of course, there are tons of API formats and specs (like JSON API or RAML - that I came to know in this very issue), not to mention serialization / normalization techniques and formats which can drive someone (like me) crazy when thinking overalls - web, mobile, custom clients ... And so on. My comment may sound more like a philosophical question rather then about specs itself, but instead of embracing all these specs in a milestone (I've seen only two in hug issues so far), wouldn't it be better to provide a common way (read as lots and lots of more info, yet if possible) in your existing documentation system to provide extensions, either to generate "anything" (like the yaml one) or single pieces (read docs, specs, inputs, outputs, etc), implemented or to be implemented by you (the lead project developer) or anyone in the community? I'll leave my question as this for now, since it already broads a wide range of topics and could be quite bigger ... 😰 Please, let me know if anything pops up from here - I'll be glad to help! 😉

[horvathcom]

I think I was the one that suggested RAML. Our company has been debating RAML vs Swagger for a few years now. My take is that OpenAPI/Swagger have won, but also agree with the earlier part that RAML rocks. I think your documentation plugin idea is a good idea. On Jun 13, 2017 11:24 AM, "Richard K" <notifications@github.com> wrote: Sorry if this isn't the right place (or time) to share my comment, but finding myself in a middle of a research for what (technologies) to use in a new project, it's getting harder and harder to select any that seeks to be "peaceful" around formats. Let me be more specific, or at least you'll try to. I came across hug by a reference in the marshmallow wiki <https://github.com/marshmallow-code/marshmallow/wiki/Ecosystem> - great project by the way! It's interesting to me any auto-generated documents, but like as many other developers I was searching for some standard spec that could be "simply added" to my project so third parties could test and explore the API for future integrations - being the OpenAPI spec one of personal interest. Of course, there are tons of API formats and specs (like JSON API or RAML - that I came to know in this very issue), not to mention serialization / normalization techniques and formats which can drive someone (like me) crazy when thinking overalls - web, mobile, custom clients ... And so on. My comment may sound more like a philosophical question rather then about specs itself, but instead of embracing all these specs in a milestone <https://github.com/timothycrosley/hug/milestone/1> (I've seen only two in hug issues so far), wouldn't it be better to provide a common way (read as lots and lots of more info, yet if possible) in your existing documentation system to provide extensions, either to generate "anything" (like the yaml <https://github.com/timothycrosley/hug_yaml> one) or single pieces (read docs, specs, inputs, outputs, etc), implemented or to be implemented by you (the lead project developer) or anyone in the community? I'll leave my question as this for now, since it already broads a wide range of topics and could be quite bigger ... 😰 Please, let me know if anything pops up from here - I'll be glad to help! 😉 — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#163 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ABjBvqubd95CoH8W--gQcv_cHpZ9ZXwUks5sDre_gaJpZM4HRK8R> .