Please add documentation outlining the steps required to add Swagger to an existing project

[behrangsa]

Looks like Swagger at the moment supports the following frameworks:

• connect
• express
• hapi
• restify
• sails

It would be great if there was documentation showing how we can add swagger to existing projects.

[mariofts]

I agree. I'm having serious issues trying to do it.

[chainlink]

+1

[harindaka]

Is this even pissible with this npm module?

[theganyo]

It is possible, certainly: Swagger-Node just relies on the standard frameworks (eg. connect). But moving any particular project to swagger-node would depend on the specific framework being used and what your expectations are for the resulting application. I don't know that this can be answered well in the abstract.

[JacquesPerrault]

I just "swaggerized" my existing express app; it was a bit frustrating, especially given that I had not previously used Swagger. It came down to a few "simple" steps:

1. install swagger (obviously) via npm install -g swagger
2. create a swagger app via swagger project create hello-world. Bear with me here - you'll just use some of the files from hello-world to bootstrap your node project
3. manually create /api/swagger and api/controller paths in your existing node app
4. copy config/default.yaml from hello-world to the /config path in your node project
5. copy api/swagger/swagger.yaml from hello-world to the /api/swagger path. At this point, you should be able to use swagger project edit to start defining your node endpoints in Swagger. Unfortunately, I haven't found anything out there that turns a response from a node endpoint into a swagger definition, but that's not to say it doesn't exist. On the upside, there are quite a few examples out there. Tip: I wasted a LOT of time trying to externalize the definitions: in swagger.yaml. It is possible, but it ain't easy, and it ain't pretty. Until there is better support for this (or you have a dedicated dev team), I highly recommend just keeping it all in swagger.yaml and focus on turning your node route logic into controller snippets.
6. create your controller code and place the files in api/controller. You can look in the hello-world api/controllers/ path for examples. That will get you to the point where you can use swagger project run

[ameliariely]

Hey! I agree that this is a problem. @JacquesPerrault 's description is the best thing I've found so far. Is there not a way to automatically generate definitions given a pre-existing API? Should I be annotating my code? I can't seem to find any useful annotations for Javascript. Any help is much appreciated!

[JacquesPerrault]

@brunerson These definitions might provide you with a good starting point.

A few notes:

1. I take advantage of the x-swagger-router-controller: parameter to give my controller filenames more intuitive naming
2. It took me a little while for figure it out, but getreposResponse: is a good example of how to include an array of objects in a response
3. getreposResponse: is just one example of where I needed to define the response as 'type: string', even though it is really an object, in order to support a JSONP response.

[timur-perelmutov]

+1 Having an official manual on adding Swagger support to an existing node.js RESTful service with arbitrary layout would be very helpful.

[zphingphong]

+1

[codercurtis]

+1

Just some instructions that detail how to set the paths to your own controllers would be nice.

[JacquesPerrault]

@codercurtis does this help?

[JacquesPerrault]

There is also a very interesting way of modularizing it documented here

I found the article was just slightly out of date, but if you look at his repo (referenced in the blog) it is current. I have a working version that I can post to a git repo if you need an example.

[hpsharon]

+1