outmoded / lout

API documentation generator
Other
276 stars 49 forks source link

Display sample request/response #40

Closed geek closed 10 years ago

geek commented 10 years ago

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 commented 10 years ago

+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 commented 10 years ago

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 commented 10 years ago

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 commented 10 years ago

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 commented 10 years ago

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 commented 10 years ago

@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 commented 10 years ago

@Marsup The routes are not grouped, they are close together: image 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: StrongLoop API Explorer

yoitsro commented 10 years ago

@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:

screen shot 2014-05-08 at 10 54 38

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 commented 10 years ago

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 commented 10 years ago

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 commented 10 years ago

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

seanrucker commented 9 years ago

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

Marsup commented 9 years ago

Same thing ?

seanrucker commented 9 years ago

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 commented 9 years ago

This might be a problem with hapi then.

Marsup commented 9 years ago

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 commented 9 years ago

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

kole commented 9 years ago

@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 commented 9 years ago

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.