-
Notifications
You must be signed in to change notification settings - Fork 26
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Missing description of each resource/high-level section #16
Comments
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 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) |
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. |
Ah you're right, for now |
Out of curiosity @FredKSchott, are you currently using Swagger? We have some ideas for the future of |
(whoops, hit enter too soon) Nope, we rolled our own framework. For now, can we include an 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() {
// ... |
I think it might only include the Markdown if there's a corresponding 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. |
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:
If there's some interest, I might work on |
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.
The text was updated successfully, but these errors were encountered: