integrating Swagger with existing sails project

[varunsingh9]

Hi , I have an existing Sails app and I want to generate the API documentation dynamically.Tried writing the details, summery etc. parameters in the route.js of my sails app ,but it is not coming up in /swagger/doc '/api/commonQuestions': { controller:'CommonQController', action:'index', swagger:{ method: [ 'GET' ], summary: 'gets Common Qs', description:'common questions 11', produces:'application/json', tags: [ 'common Questions' ], responses: { '201': { description: 'Product created', schema: 'user' //model } }/*, parameters: [ 'products' ]*/ } },

[joseasrocha]

Hi @varunsingh9,

Try something like this: 'GET /api/commonQuestions': { controller: 'CommonQ', action: 'index', swagger: { methods: ['GET'], summary: 'gets Common Qs', description: 'common questions 11', produces: [ 'application/json' ], tags: [ 'CommonQ' ], responses: { '200': { description: 'CommonQ List', schema: 'CommonQ' } }, parameters: [ { "name": "$query", "in": "body", "description": "Query string to search", "required": true, "schema": { $ref: '#/definitions/CommonQ' } } ] } }

The schema is the model name and the controller must be defined without the "Controller" word. In Parameters you must use something like my example above.

Hope this helps.

[rekdave]

Hello,

I am running into something very similar. The /swagger/doc is working and auto-generating documentation about the Controllers, etc, etc, in this example, the /swagger/doc is printing the following excerpt:

"/something": { "get": { "summary": "Read Object(s)", "consumes": [ "application/json" ], "produces": [ "application/json" ], "responses": { "200": { "description": "The requested resource" }, "404": { "description": "Resource not found" }, "500": { "description": "Internal server error" } }, "tags": [ "Something" ] } },

...but when I try to add additional information ( summary:, description:, parameters:, responses:, etc, etc ) in the config/routes.js, none of those changes are pulled in and the /swagger/doc remains static. An example of what I have in config/routes.js is:

'get /something': { controller: 'somethingController', action: 'dataTable', skipAssets: 'true', swagger: { methods: ['GET'], summary: 'This is the summary...something something dark side, something something force', description: 'This is the description...something something dark side, something something force', produces: [ 'application/json' ], tags: [ 'Something' ], responses: { '200': { description: 'The requested resource, something something', } }, parameters: [] } }

Trying to get the summary: or description: pulled through before I moved on to the more functional areas.

I have been digging around in the source to see what is up and have not had any luck so far.

Any thoughts or pointers? And/or am I misunderstanding that I cannot supersede the generated /swagger/doc by adding details in the config/routes.js?

Thanks and best!

[joseasrocha]

@rekdave you must reference the controller like this:

controller: 'something', Note that the controller name must not include the ending "Controller" part.

Hope this helps.

[devendra1102]

same problem with me, anyone found the solution?

[rekdave]

Hello, @joseasrocha , thanks for taking the time to answer. End goal was to have the swagger markup in the routes.js file (rather than a separate file). I was not able to get that to work by removing the "Controller" characters from the controller: section, my example:

in routes.js 'get /somethingDataTable/uid/:uid': { controller: 'somethingController', action: 'dataTable', skipAssets: 'true' /* * This should work but doesn't, latest information is here: * https://github.com/langateam/sails-swagger/issues/31 */ swagger: { summary: "Beep boop beep boop Read Object(s)", description: "Beep boop beep boop This API/Controller is consumed by the client side front end API." } },

Possibly additional information could help. Also, unclear why "Controller" needs to be removed, I couldn't get that to work.

@devendra1102 , I could not figure out how to make it work so I moved the documentation directly into the assets/docs/swagger.json and that worked but was not the desired solution:

$ grep -A10 somethingDataTable assets/docs/swagger.json "/somethingDataTable": { "get": { "summary": "Beep boop beep boop Read Object(s)", "description": "Beep boop beep boop This API/Controller is consumed by the client side front end API.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "responses": { . . .

I am open to collaborating further, but that is all the information I have at the moment.

Swagger is working when I document everything in the swagger.json file, but ideally we would like to put the swagger markup in the routes.js file as shown in some of the examples.

Best.