search

matryer / silk

Markdown based document-driven RESTful API testing.
http://silktest.org/
GNU General Public License v2.0
942 stars 69 forks source link

Blueprint compatible? Differences? #35

Closed joyrexus closed 8 years ago

joyrexus commented 8 years ago

Just curious to what extent silk's syntax and conventions are similar and/or compatible with blueprint? I ask, because blueprint is a pretty established standard for documenting web APIs (along w/ Swagger and RAML, all of which are interconvertible) and there's already a lot of nice tooling around it (e.g., test2doc).

If different, is it possible to convert silk-based api docs into blueprints or other api-spec formats?

matryer commented 8 years ago

Silk was designed without knowledge of Blueprint, and follows some core principals from the Go community around simplicity and the use of whitespace. Aside from that, it's pretty similar to Blueprint. I take the lead of where a project should go from the community of people who use it, so it's up to everyone what features we add etc. I'd say people should use Blueprint for now if they need all that extra tooling etc, Silk is designed to be extremely simple.

Genuine question: If you want to convert Silk files to Blueprint, why are you using Silk and not Blueprint?

joyrexus commented 8 years ago

Appreciate the response.

If you want to convert Silk files to Blueprint, why are you using Silk and not Blueprint?

Good point. Various colleagues of mine already use Blueprint and I originally found Silk by looking for Go based tooling for the spec. Dredd can be used for testing Blueprints in a similar manner and there's even setup/teardown hooks for Go. It's Node based, which is fine, but I always look for Go variants of python/ruby/node utilities because they're often simpler, faster, better engineered, and less dependency heavy. I'm more likely to contribute to Go-based projects and/or modify them for my own idiosyncratic needs.

Both Silk and Blueprint are Markdown-based conventions for describing web APIs ... very similar ways of describing the same thing. So I guess my question was actually less about converting Silk Markdown descriptions to Blueprint Markdown descriptions than about the rationale for introducing a variant format. (You explained that.)

Sort of wondering now if it would be terribly difficult to fork Silk and use it as a basis for parsing Blueprint docs ... but this is more off the cuff curiosity about the possibility than anything else.

matryer commented 8 years ago

I'd be interested to see any experiments in this area if it's something you want to pursue.