Markdown documentation based on registered endpoints about rack-app HOT 13 CLOSED

Creating a documentation object that allow adding sections would enable extension to add they documents to the endpoint definitions without any dependency on any markup language

from rack-app.

Creating an extension would allow to use kramdown and cli command to be registered into the developers main application.

With this creating documentation by only the endpoint definitions become easy job and help the developer to focus on spec based bdd testing while always be able to update the documentation with a build pipeline step.

from rack-app.

I think it's better to remove your "desc" and "validate_params" to the other gem and try to make swagger.io as describing standard.
Also, I want to use dry-validation to validate my params (and response correct errors) but I don't want to drag your describing-validation standard.
Don't repeat the code of other developers, please. Dry-validation is better for validation, swagger is better for documentation. You can't do all this work.

I love your work, thank you.

from rack-app.

Hello @ifokeev ! First of all, thank you for using, or playing with this framework.
It's a real honor and I hope you have a good time with it!
You have a really good point, even if it's sad from the perspective that I can't have all the fun creating everything by my hand... At least I tried :D

I can't promise anything now, only that I will dive into this idea, and create some spike, to see how they can work.

The swagger compatibility was already in plans anyway! :)))
And the dry-validation looks really promising!
Thank you for adding a new perspective to this topic! ^~^

from rack-app.

But what is with the principle of "Only dependency is rack, nothing more"? Or did I miss something?

from rack-app.

@janfri , yes you are right, but the "one dependency is rack" only limited to the rack-app core.

If someone for example would like to use a "rack-app-dry-validation" extension, by choosing that extension, (s)he accept the additional dependency direct. The main reason to exclude dependencies from the rack-app core is to, not enforce anything on the developer, and guaranteeing that the ruby constant namespaces are clean ,the ruby core classes monkey patch free as how they should be.

But for example the prototype rack-app-front_end extension also use additional dependency which is the Tilt template handler interface.

This principle allow, that for simple API -s you don't need anything else than the rack dep and you good to go.

btw, welcome back @janfri ! I missed you :D
I finished your request, and it's already rolled out! If you mind you can still commit to that issue, and if you require anything more to that, I will happy to reopen and listen to you. :)

from rack-app.

@adamluzsi One reason for me to using rack-app is the included documentation functionality. So it would be nice to have this further without to have to use a third party library.

from rack-app.

@janfri Because the rolling release nothing will be removed at such level. It's more like @ifokeev suggest that we should create an extension that use more feature rich validation with dry-validatie and can create a swagger compatible documentation, which is awesome.

I don't have user stories to backup this epic , so while I create this extension , I still want to continue with my original plan and if nothing else, I make a dark launch with the two , to see some real life experience.

from rack-app.

@ifokeev suggest that we should create an extension that use more feature rich validation with dry-validatie and can create a swagger compatible documentation

I don't mean that you (we) should create dry-validation extension. I mean that you can put your validation in other gem and this way keep your rack-app core clean (Developer can install this gem if it's necessary).
There are a lot of cases of validation and your way shouldn't be a standard.

The same is with swagger.
We could use https://github.com/Gild/ruby-swagger or https://github.com/fotinakis/swagger-blocks

How I code now:

• I put all my business-logic inside Interactors (that's an amazing tool that you should look at) https://github.com/collectiveidea/interactor
• I validate all input data in each Interactor with dry-validation (the same way I can validate output data)
• All my "actions" look now like

    result = CreateUser.call(params)

    if result.success?
      json_success({ success: true })
    else
      json_error(result.error)
    end

• ....
• I have no pain and can test all my app via interactors (because It's based on interactors at all)

All I need from ruby now is a tool like rack-app core.

from rack-app.

Hmm, nice. I think about a good solution, please give me some time. In the mean time , if you have any more information like how would you like to write the rack-app class for this scenario, that would be great !

The params validation in the rack-app is nothing more, just syntax sugar for endpoint based validation middleware registration only for the next endpoint middleware stack. If the method it self not bother you , so you not sad only because it's existence in the project , than I can focuse more on your use case. :)

from rack-app.

if you have any more information like how would you like to write the rack-app class for this scenario, that would be great !

I'll try.

The params validation in the rack-app is nothing more, just syntax sugar for endpoint based validation middleware registration only for the next endpoint middleware stack

The main problem that it's in the documentation now and makes some standard but it should give you the freedom.

from rack-app.

@ifokeev if it's in the documentation, it is only because I can't work without BDD and I have to create spec files for every feature that I create in the project. On the other hand, it's true it is a tool that can be used, but nothing like it removes the freedom to use anything else, or I wasn't aware of this. Can you explain, how do you feel this, and what's the real root cause, like you forced to do this by any means. It could be valuable information to avoid this kind of behavior in the future developments!

from rack-app.

there are a lot of nice solutions already, that can be used for building documentations.
If a user story appears for that to justify, I will reopen the issue.

from rack-app.