search

apiaryio / dredd

Language-agnostic HTTP API Testing Tool
https://dredd.org
MIT License
4.19k stars 279 forks source link

Find a better way how to organize examples for hooks in the docs #527

Open honzajavorek opened 8 years ago

honzajavorek commented 8 years ago

Some of how-to examples on the http://dredd.readthedocs.io/en/latest/hooks-nodejs/#examples page do not need to be JS-specific and could be generalized and added to http://dredd.readthedocs.io/en/latest/overview/ Maybe also other hooks pages contain similar examples (didn't check thoroughly).

We have many how-to examples/guides in the docs: http://dredd.readthedocs.io/en/latest/how-to-guides/ Some are general, some are specific for a particular language, but often they're scenarios to follow, which could be easily transformed to an actual test. It would be cool to have all these examples tested so we're sure we're not advising some outdated things or that what we advise really actually works.

Super-simple idea would be to have tests with fixtures and to use exactly these fixtures in the docs (contents of the fixture file included to the docs as a highlighted code block).

Another crazy idea was to write the examples as tested Gherkin scenarios and then generate the docs from those. This would have many challenges, especially how to keep readability of the tests (reading step-by-step scenario is actually quite inconvenient experience in comparison with a nice explaining free-form text in the docs).

w-vi commented 7 years ago

These examples are in other languages too, all of them were rewritten.

http://dredd.readthedocs.io/en/latest/hooks-perl/#examples http://dredd.readthedocs.io/en/latest/hooks-php/#examples http://dredd.readthedocs.io/en/latest/hooks-python/#examples http://dredd.readthedocs.io/en/latest/hooks-ruby/#examples

So I think this one can be closed.

honzajavorek commented 7 years ago

I had a feeling some examples were added just to JS hooks docs. When I'm looking at it, just Remove trailing newline character in expected plain text bodies is present in JS hooks docs and not anywhere else. And while it's very common issue, it should be accessible for users of any hooks, thus it should be potentially moved to How-To Guides.

I'm still a bit grappling with the fact these examples are IMHO dispersed all over the docs. In ideal world, all of them would be available in all the languages and it would be all in one page, e.g. the How-To Guides one. And they would be tested 😈 (I know, I'm dreaming here). I'll rename this issue to better represent my actual issue.