Display sample request/response

[geek]

If an endpoint has a payload validation schema then we can generate a sample request payload to display (Instead of adding mock data, it could be { "item": "string", "item2": 100 }

If the endpoint also has response validation then we can also provide a sample response body.

[papajuans]

+1. What about adding an example() or sample() method to joi? Then when lout inspects the routing table and finds validation rules within a route, the sample() values can just be displayed on the page.

[Marsup]

I agree it would be nice, but this is probably not joi's concern. It will be complicated to generate a coherent object considering all the possibilities (or, xor, ranges, array.includes, ...), I'll try to think of a good way to achieve this.

[Marsup]

Well I have tried to think about it and after all, including it in joi might be the way to go, @hueniverse would you consider letting people provide samples in their joi definitions ? Automatic generation would be nice but only if nothing is provided, if this is supposed to be a documentation people should be able to set meaningful samples for their use cases.

[ueqt]

Hello, further more, can we output like what LoopBack did?
http://docs.strongloop.com/display/DOC/Using+the+LoopBack+sample+app#UsingtheLoopBacksampleapp-UsingtheAPIExplorer

In that case, we can input the Parameters on the example page, and after click "Try it out" button, we can see the response directly

Another enhancement is that we need group the routes, such as group /locations/* POST,GET and any parameters together, after click through, we can see the detail locations routes.

Best regards.

[yoitsro]

LoopBack are essentially using Swagger. There is already a port of Swagger for Hapi:
https://github.com/glennjones/hapi-swagger

As far as personal preference goes, I prefer Swagger. It means that API consumers can get hands on with the API very easily. On the other side though, it also means that when it comes to Joi's alternatives, things could get very messy, very quickly. Still, anything's possible.

@Marsup, what do you think about a Swagger-like interface?

[Marsup]

@ueqt I think the routes should already be grouped, is it not ?

@yoitsro I personally never had any interest in the interactive side of swagger. If the documentation is well made and the API actually does what it tells, I don't need that, it doesn't help me use it in my own context, but I guess I can understand people wanting it.

Since I think it's a different issue from this one, I'm creating another one to track this.

[PaulMougel]

@Marsup The routes are not grouped, they are close together:

What I think @ueqt meant was to have a single line for myResource which you can click on and reveal all methods available, as is done in the StrongLoop API Explorer:

[yoitsro]

@Marsup Thanks for that. I'll take a look at getting something done for that at some point.

In relation to @PaulMougel's comment above, even if there was an interface similar to Swagger's just for reading the endpoints, that would still be great. When one of the endpoints is expanded, it looks like this:

IMO, it is a much nicer design, both visually and for usability, than having all the endpoints and their verbs listed at once.

Whatever the case, thank you :)

[Marsup]

My problem with that is what do you pick as the grouping factor ?
The first element of the path ? What if my routes are organized in the sub levels (eg. /api/v3/...) ?

[yoitsro]

You could leave it to the developer to define the root path as an optional parameter when setting lout up.

I guess the whole point of a RESTful API is to be able to CRUD resources at the path specified. Obviously, not all APIs are going to be RESTful, but it could be possible to group by the resource in question. For example:

albums
GET /albums
POST /albums
DELETE /albums

albums/{albumId}
GET /albums/{albumId}
PATCH /albums/{albumId}
PUT /albums/{albumId}
DELETE /albums/{albumId}

albums/{albumId}/songs
GET /albums/{albumId}/songs
POST /albums/{albumId}/songs
DELETE /albums/{albumId}/songs

albums/{albumId}/songs/{songId}
...

Another alternative is what Swagger currently does, which is to just group by the first resource. In my opinion, this isn't very useful:

albums
GET /albums
POST /albums
DELETE /albums
GET /albums/{albumId}
PATCH /albums/{albumId}
PUT /albums/{albumId}
DELETE /albums/{albumId}
GET /albums/{albumId}/songs
POST /albums/{albumId}/songs
DELETE /albums/{albumId}/songs

Another alternative is to manually tag each route with its group, but that feels a little clunky to me.

[Marsup]

This issue is now fixed, open new issues for those last discussions if you want it.

[seanrucker]

I see that using .example() I can now provide sample payloads, but what about sample responses?

[Marsup]

Same thing ?

[seanrucker]

I had sample set to 0 as I don't actually want to validate my API responses, I was just using it for lout. In this case, lout was not generating any response documentation. Changing sample to > 0 fixed the problem.

[Marsup]

This might be a problem with hapi then.

[Marsup]

I don't think there's anything I can do about that : https://github.com/hapijs/hapi/blob/d7fd5a8845d9f089978b83a3989d7ece799fc49c/lib/route.js#L108-L112

[seanrucker]

No worries, I can work around this. Thanks for looking into it!

[kole]

@Marsup I'm not sure I understand the answer to @seanrucker request for providing sample responses. Are you saying to also use example() for that? If so, I don't see how that works with lout. Can you explain the right way to provide sample responses?

[Marsup]

That's right, the only way to do that currently is to use .example(), probably at the top level since it doesn't go down the validation tree to build a sample.