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:
* #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.