Missing description of each resource/high-level section

[FredKSchott]

Hey @rprieto, thanks for building this awesome library!

Have you considered adding the ability to describe each resource? For example: in the HTML output, a description at the top of each page would be incredibly helpful for describing what that resource is for, some general rules about working with it, etc.

Example: https://developers.box.com/docs/#folders

Folders
Folders contain information about the items contained inside of them, including...

[rprieto]

Hi @FredKSchott, glad to hear it's useful!

That's a good idea, not sure how to implement it yet. What we currently do, that might solve your requirement, is the first example for each resource includes a little paragraph in the Markdown section.

For example:

it '''
# Folders

> Folders contain information about the items contained inside of them.
> Example: [https://developers.box.com/docs/#folders](https://developers.box.com/docs/#folders)

Here's some examples of valid folder requests:

1. Return the list of items in a folder
''', (done) ->
  request(server)
    .get('/folder/123')
    .end(done)

it '''
2. Add an item to the folder
''', (done) ->
  request(server)
    .post('/folder/123')
    .send(name: 'my_file')
    .end(done)

[FredKSchott]

Oh interesting. We use describe blocks to group resources/logic, like this:

describe('Folders', function() {
  describe('Get', function() {
    itAsync('Return the list of items in a folder', function() {});
    itAsync('Some special behavior we want to illustrate', function() {});
  });
  describe('Update', function() {
    // ...

Can you include a little paragraph in either of the describe blocks? (I tried doing it but it did not work.) If that did work, then we could include a general explanation of the "Folders" API/Resource in the "Folders" describe block.

[rprieto]

Ah you're right, for now describe blocks are only used for grouping / navigation, and it blocks are used to store Markdown and examples. I'll have a think about how this could be done, or if you have some ideas please share :)

[rprieto]

Out of curiosity @FredKSchott, are you currently using Swagger? We have some ideas for the future of supersamples to be more swagger-friendly, so could use your opinion if you're interested. Cheers

[FredKSchott]

(whoops, hit enter too soon)

Nope, we rolled our own framework.

For now, can we include an it() test with the resource description we want & no test? Something like:

describe('Folders', function() {

  it('Here is where i will describe the folder object. This description will be multiline markdown');

  describe('Get', function() {
    it('Return the list of items in a folder', function() {});
    it('Some special behavior we want to illustrate', function() {});
  });
  describe('Update', function() {
    // ...

[rprieto]

I think it might only include the Markdown if there's a corresponding request. That's a limitation of supersamples, that it's based on a list of examples, each with associated Markdown. If you're interested in having a look, happy to accept any PRs!

FWIW, we're thinking of decoupling supersamples to have the request/response extraction on one side, and the Markdown editing/rendering on the other side. Might have to become another project though.

[rprieto]

I've had another think about it, and can't think of a way to solve this for now.

However my current project has also started to hit limitations, where we'd want more control over the Markdown and what gets displayed. Maybe this will work for you, we've slowly moving towards:

• sill extracting all the req/res using supersamples
• writing them to disk using the JSON reporter
• handwriting separate Markdown files, with whatever structure we want
• referencing samples from the Markdown with a custom syntax (e.g. {sample "my example"})
• processing and rendering the Markdown as a separate task - you might be interested in gitbook

If there's some interest, I might work on Gitbook integration, where supersamples would then mostly focus on extracting the req/res into a good machine-processable format, and less on rendering.