feat: add @response tag (#21)

Author: rawmind

README.md

@@ -43,7 +43,8 @@ node -e 'require("express-autodoc").generateSwagger(".")'
 | @queryParam       | (\<name\>) {type: string, required: true, default: \<defaultValue\> } \<description\> | `/** @queryParam (name) A name param */` |
 | @pathParam        |  (\<:name\>)  \<description\>                                                         | `/** @pathParam (:id) song Id */`        |
 | @produces         | \<contentType1\>,\<contentTypeN\>                                                     |  `/** @produces application/json */`|                                      |
-| @description      | \<description\>                                                                       | `/** @description A description */`      |
-| @body             | \<body\> [{"example": "object"} |<reference>]                                        | `/** @body {} */` `/** @body #definitions/Song */` |
+| @description      | \<description\>                                                                       | `/** @description A description */`                |
+| @body, @request             | \<body\> [{"example": "object"} |<reference>]                               | `/** @body {} */` `/** @body #definitions/Song */` |
+| @response             | \<response\> [{"example": "object"} |<reference>]                                 | `/** @response {} */` `/** @response #definitions/Song */` |
 
 ### See more examples: [simple app](examples/singleApp/), [app with router](examples/withRouter/)

examples/singleApp/app.js

@@ -90,6 +90,7 @@ app.head('/api/v1/song/:id/*', (_req, res) => (
 /**
  * @description Updates a new song
  * @body #/definitions/Song
+ * @response #/definitions/Song
  */
 app.post('/api/v3/song-json', (_req, res) => (
   res.json({

examples/singleApp/swagger_output.json

@@ -177,7 +177,11 @@
         ],
         "responses": {
           "200": {
-            "description": "OK"
+            "content": "application/json",
+            "description": "OK",
+            "schema": {
+                   "$ref": "#/definitions/Song"
+            }
           }
         }
       }

examples/singleApp/swagger_output_with_config.json

@@ -191,7 +191,11 @@
         ],
         "responses": {
           "200": {
-            "description": "OK"
+            "content": "application/json",
+            "description": "OK",
+            "schema": {
+                   "$ref": "#/definitions/Song"
+            }
           }
         }
       }

package.json

@@ -1,6 +1,6 @@
 {
   "name": "express-autodoc",
-  "version": "0.0.15",
+  "version": "0.0.16",
   "description": "",
   "main": "src/traverse.js",
   "scripts": {

src/parser/EndpointDoc.js

@@ -15,7 +15,8 @@ class EndpointDoc {
             }, {})
         this.queryParams = tags.filter(t => t.title === 'queryParam')
             .map(t => QueryParam.parse(t.description))
-        this.body = tags.find(t => t.title === 'body')?.description
+        this.body = tags.find(t => t.title === 'body' || t.title == 'request')?.description
+        this.response = tags.find(t => t.title === 'response')?.description
         this.pathParams = this.extractPathParams(path).map(paramName => `:${paramName}`).map(paramName => new PathParam(paramName).merge(docParms[paramName]))
         this.produces = tags.filter(t => t.title === 'produces').map(t => new ProducesTag(t.description))
     }
@@ -121,6 +122,17 @@ class SwaggerBody {
     }
 }
 
+class SwaggerResponse {
+
+    constructor(body, contentType = 'application/json') {
+        if (body.startsWith('{')) {
+            this.value = { content: contentType, schema: { type: 'object', example: body } }
+        } else {
+            this.value = { content: contentType, schema: { $ref: body } }
+        }
+    }
+}
+
 class SwaggerEndpointPath {
 
     constructor(path, pathParams) {
@@ -158,4 +170,5 @@ exports.SwaggerPathParam = SwaggerPathParam
 exports.SwaggerEndpointPath = SwaggerEndpointPath
 exports.SwaggerQueryParam = SwaggerQueryParam
 exports.ProducesTag = ProducesTag
-exports.SwaggerBody = SwaggerBody
+exports.SwaggerBody = SwaggerBody
+exports.SwaggerResponse = SwaggerResponse

src/swagger/ExpressProject.js

@@ -1,6 +1,6 @@
 const { defaultConfig } = require('./config')
 const fs = require('fs')
-const { SwaggerPathParam, SwaggerEndpointPath, SwaggerQueryParam, SwaggerBody } = require('../parser/EndpointDoc')
+const { SwaggerPathParam, SwaggerEndpointPath, SwaggerQueryParam, SwaggerBody, SwaggerResponse } = require('../parser/EndpointDoc')
 const { parse } = require('path')
 
 class ExpressProject {
@@ -56,10 +56,12 @@ function createPath(endpoint, rootPath, paths) {
   const produces = doc.produces.flatMap(p => p.produces)
   const body = doc.body
   const bodyParams = body ? [new SwaggerBody(body).value] : []
+  const response = doc.response
+  const responseBody = response ? new SwaggerResponse(response).value : {}
   path[endpoint.method] = {
     description: doc.description,
     parameters: pathParams.concat(queryParams).concat(bodyParams),
-    responses: { '200': { description: 'OK' } },
+    responses: { '200': { description: 'OK', ...responseBody } },
   }
   if(produces && produces.length > 0){
     path[endpoint.method].produces = produces