Markdown (APIBlueprint) Support

[voltechs]

Hi all,

This is a big PR, but I think it is a good one.

There are definitely some breaking changes in here, so it might need a bigger discussion.

Breaking Changes:

• hash => object
• numeric => number
• errors are now simply a response, the "error-ness" of it is implied via the response code and interpreted by humans.
• DSL changed slightly to be a little more consistent (all responses need a code, second param is the body of the response)

Improvements + Additions

• Broke out large files into sub-files based on classes (see DSL)
• Markdown/APIBlueprint support!!

Happy to discuss these changes :)

[iNecas]

Hi,

First of all thanks for doing this: I believe this is an important move that one needed to do for getting apipie to the next level.

Before we go deeper into the discussion, I would suggest investing time to keeping the backward compatibility: apipie has been here for a while and we introduced very little (if any) backward incompatibile changes. If nothing else, we will need a path though deprecations, but I'm more in favor of aliases, unless it harms the code.

This is easier to achieve on DSL level, and could be harder for json output format. In ideal world, we should have a period where we provide both json formats and then we can either: deprecate one over the other; or keep multiple formats and leave it as a benefit to be able to define another formats if needed, and from some disucssion we had previously (#325 (comment)), there might be other formats in play, such as Swagger, so this option might be the way to go.

[micapam]

Looks like this PR has gone stale, but it's a feature I'm keen to see supported.

Assuming @voltechs is no longer interested in this PR - I could pick it up, potentially? Let me know if there's still interest among the maintainers in this feature.

[voltechs]

Hey @micapam!

I’m definitely still interested in supporting this, but the requirement for backwards compatibility is where I checkout. Love the concept and the initial pass, but there is are some architectural choices that should be revamped and major version reving makes the most sense to me. I’m currently contributing to a lot of other repos, and have been contemplating a fully new greenfield offshoot of apipie (yay opensource) but I’d much rather contribute to an existing project.

Feel free to fork and progress if you see a good path forward, I support it!