search

hugapi / hug

Embrace the APIs of the future. Hug aims to make developing APIs as simple as possible, but no simpler.
MIT License
6.86k stars 389 forks source link

auto generate RAML documentation #163

Open timothycrosley opened 8 years ago

timothycrosley commented 8 years ago

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 commented 8 years ago

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

wing328 commented 8 years ago

@mvillis I opened https://github.com/timothycrosley/hug/issues/198 for tracking.

jacobsvante commented 8 years ago

RAML is awesome. Could make for a killer combo 😀

vltr commented 7 years ago

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 ... :cold_sweat: Please, let me know if anything pops up from here - I'll be glad to help! :wink:

horvathcom commented 7 years ago

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 https://github.com/timothycrosley/hug/issues/163#issuecomment-308172072, or mute the thread https://github.com/notifications/unsubscribe-auth/ABjBvqubd95CoH8W--gQcv_cHpZ9ZXwUks5sDre_gaJpZM4HRK8R .