New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
auto generate RAML documentation #163
Comments
equally, auto generation of a swagger (openapi) spec would be useful. |
RAML is awesome. Could make for a killer combo 😀 |
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 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>
.
|
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/
The text was updated successfully, but these errors were encountered: