Create an API documentation page based on the files

[sideshowcoder]

Scanning through the directory to explore the API is nice but it would be great if it would be possible to output a simple HTML page which just lists the available endpoints with their requests.

Something like seen in the readme for showing what canned can do.

[peinguin]

Hello. My name is Sergei. I have an idea about issue#16. My code has few problems. But I want show it to you. I use swagger-ui. And not display's root folder, but can if need. If you like that idea - we may discuss next steps for improving it.

[sideshowcoder]

Hi Sergei, I really like the idea, I just scrolled through the code real quick and it looks like a good approach really. One thing I would love to have so would be the option to turn it off, so the idea would be to make it more like a plugin you activate instead of having it always available. Maybe we can define a hook to hook into the canned method to inject stuff like this before we route to canned this would open it up for more processing since I think their will be some parts you want to filter out of the docs for example.

It is a great start and thanks for taking this on!

For reference the pull request is #38

[peinguin]

I define some like router in canned.js. But file "swagger.js" is like a plug-in. It is possible to add support for plug-ins. And modify router. Also I can add method setFolder. And setApiUrl. And configure plug-in through them.

[sideshowcoder]

That sounds like a good idea, so I would suggest moving the swagger.js file to a extensions folder, and make its loading configurable maybe passing something like this on the command line

$ canned --extensions swagger

and then instantiate swagger with the setFolder and setApiUrl and such so it can be passed.

if(extensions.swagger) new Swagger(options)

The reason for all this really is that love the concept of doing this with swagger but I also see that a lot of people don't want to use swagger so keeping it configurable seems like a good way to go for now.

What do you think about that?

[peinguin]

I try to realize it tomorrow. Another version

$ canned --include swagger "{endpoint: 'swagger'}"

And JS

includes.forEach(function(include){
  fs.stat(include.name, function(stat){
    if(!stat.isDirectory())
      return fasle

    var extension = require('./extensions/'+include.name+'/main.js')
    new extension(include.options && JSON.parse(include.options))
  })
});
}

Or something like this.

And it would be nice to add extensions to express chain.

[peinguin]

Please see 4a82e08 I ass express. Designed as separate module. And add extensions mechanism.

[peinguin]

Try

$ ./bin/canned ./example/
$ ./bin/canned ./example/ --extensions=swagger,notexist
$ ./bin/canned ./example/ --extensions=swagger,notexist --swaggerEndpoint=docs

[sideshowcoder]

There has been work going on to use express in #33 and the branch express-canned but looking over this I'm not sure if the dependency to express adds that much. As far as I can see you use express to have the support for middleware can't you achieve the same with just using async.waterfall?

I don't mind the dependency to express if necessary but since it is quite a big dependency canned needs to track changes etc. I want to be sure we really need it.

[sideshowcoder]

(lets move the discussion to the pull request so I can comment on code :) )

[peinguin]

I add "async" variant.