jsdoc-http-plugin - npm Package Compare versions

Comparing version 0.1.0 to 0.2.0

index.js

@@ -14,2 +14,4 @@ /**
 const routeParameterTag = require('./lib/routeparam')
+const responseParameterTag = require('./lib/responseparam')
+const responseCodeTag = require('./lib/responsecode')
 
@@ -23,2 +25,4 @@ exports.defineTags = function (dictionary) {
   dictionary.defineTag(routeParameterTag.name, routeParameterTag.options)
+  dictionary.defineTag(responseParameterTag.name, responseParameterTag.options)
+  dictionary.defineTag(responseCodeTag.name, responseCodeTag.options)
 }
@@ -34,3 +38,5 @@
     routeTag.newDocletHandler(e)
+    responseParameterTag.newDocletHandler(e)
+    responseCodeTag.newDocletHandler(e)
   }
 }

lib/parameterTableBuilder.js

@@ -22,3 +22,3 @@ /**
 
-function buildTableEntry (param, columnInfo) {
+function buildTableEntry (param, columnInfo, opts) {
   const attributeCell = columnInfo.showAttributes ? `<td class="attributes">${param.optional}</td>` : ''
@@ -28,4 +28,4 @@ const defaultCell = columnInfo.showDefaultValue ? `<td class="default">${param.defaultvalue === undefined ? '' : param.defaultvalue}</td>` : ''
   return `<tr>
-            <td class="name">${param.name}</td>
-            <td class="type">${param.type}</td>
+            ${opts.name === false ? '' : `<td class="name">${param.name}</td>`}
+            ${opts.type === false ? '' : `<td class="type">${param.type}</td>`}
             ${attributeCell}
@@ -37,3 +37,3 @@ ${defaultCell}
 
-function buildTableHeader (columnInfo) {
+function buildTableHeader (columnInfo, opts) {
   const attributeHeader = columnInfo.showAttributes ? '<th>Attributes</th>' : ''
@@ -43,4 +43,4 @@ const defaultHeader = columnInfo.showDefaultValue ? '<th>Default</th>' : ''
               <tr>
-                <th>Name</th>
-                <th>Type</th>
+                ${opts.name === false ? '' : '<th>Name</th>'}
+                ${opts.type === false ? '' : '<th>Type</th>'}
                 ${attributeHeader}
@@ -53,3 +53,8 @@ ${defaultHeader}
 
-exports.build = function (title, params) {
+exports.build = function (title, params, opts) {
+  opts = Object.assign({
+    name: true,
+    type: true,
+    description: true
+  }, opts)
   const columnInfo = extraColumnInfo(params)
@@ -59,3 +64,3 @@ const paramTableEntries = []
   params.forEach((param) => {
-    paramTableEntries.push(buildTableEntry(param, columnInfo))
+    paramTableEntries.push(buildTableEntry(param, columnInfo, opts))
   })
@@ -65,5 +70,5 @@
           <table class="params">
-            ${buildTableHeader(columnInfo)}
+            ${buildTableHeader(columnInfo, opts)}
             ${paramTableEntries.join('')}
           </table>`
 }

package.json

 {
   "name": "jsdoc-http-plugin",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Plugin to add HTTP Route tags for documenting HTTP endpoints",
@@ -5,0 +5,0 @@ "main": "index.js",

README.md

@@ -96,18 +96,3 @@ # This is a fork
 The `@path` tag will add a table showing the HTTP verb (i.e. POST, PUT, DEL, GET), and the route path (i.e. /v1/files) for the route you are documenting just under the friendly name of the route above the details section.
-It would look something similar to the following:
 
---------------------------------------
-
-#### Members
-  *(path)* File Upload
-
-##### Route:
-|Method |Path      |
-|:------|:---------|
-| POST  | /v1/file |
-
-Upload a file.
-
---------------------------------------
-
 Only one `@path` tag is expected per endpoint document.
@@ -133,20 +118,3 @@
 It will result in a new sub-heading called **Authentication** with whatever text you provided to the tag beneath it.
-It would look something similar to the following:
 
---------------------------------------
-#### Members
-  *(path)* File Upload
-
-##### Route:
-|Method |Path      |
-|:------|:---------|
-| POST  | /v1/file |
-
-Upload a file.
-
-##### Authentication
-This route requires HTTP Basic Authentication. If authentication fails it will return a 401 error.
-
---------------------------------------
-
 Only one `@auth` tag is expected per endpoint document.
@@ -179,23 +147,2 @@
 The above would add a table under the route description that lists all the header parameters.
-It would look something similar to the following:
-
---------------------------------------
-#### Members
-  *(route)* File Upload
-
-##### Route:
-|Method |Path      |
-|:------|:---------|
-| POST  | /v1/file |
-
-Upload a file.
-
-#### Header Parameters:
-|Name            |Type    | Description                                       |
-|:---------------|:-------|:--------------------------------------------------|
-| authorization  |        | is the identification information for the request |
-| user-id        | String | is the unique User Id to assign to the file       |
-
---------------------------------------
-
 You can use the `@header` tag as many times as you have parameters in your request header you whish to document.
@@ -237,23 +184,3 @@
 The above would add a table under the route description that lists all the body parameters.
-It would look something similar to the following:
 
---------------------------------------
-#### Members
-  *(route)* File Upload
-
-##### Route:
-|Method |Path      |
-|:------|:---------|
-| POST  | /v1/file |
-
-Upload a file.
-
-##### Body Parameters:
-|Name     |Type     | Attributes | Default | Description                                                                  |
-|:--------|:--------|:-----------|:--------|:-----------------------------------------------------------------------------|
-| userId  | String  |            |         | is the unique identifier for the user we are uploading the file to.          |
-| sync    | Boolean | Optional   | false   | when true the route will be synchronous otherwise the route is asynchronous. |
-
---------------------------------------
-
 You can use the `@bodyparam` tag as many times as you have parameters in your request body you whish to document.
@@ -285,22 +212,3 @@
 The above would add a table under the route description that lists all the route parameters.
-It would look something similar to the following:
 
---------------------------------------
-## Members
-  *(route)* Download File
-
-### Route:
-|Method |Path               |
-|:------|:------------------|
-| GET   | /v1/files/:fileId |
-
-Download a file.
-
-### Route Parameters:
-|Name      |Type    | Description                                        |
-|:---------|:-------|:---------------------------------------------------|
-| :fileId  | String | is the unique identifier for the file to download. |
-
---------------------------------------
-
 You can use the `@params` tag as many times as you have parameters in your route path.
@@ -339,24 +247,70 @@
 The above would add a table under the route description that lists all the query parameters.
-It would look something similar to the following:
 
---------------------------------------
-## Members
-  *(route)* Download Files
+You can use the `@query` tag as many times as you have parameters in your request url you whish to document.
 
-### Route:
-|Method |Path       |
-|:------|:----------|
-| GET   | /v1/files |
+## @response
 
-Download files.
+The `@response` allows you to document the response that your route will make
 
-### Query Parameters:
-|Name      |Type    | Attributes | Description                                       |
-|:---------|:-------|:-----------|:--------------------------------------------------|
-| fileType | String | Optional   | will limit the download to just these file types. |
+With this tag you need to provide the name and a description. The name is the first word of the text following the tag.
+* `@response MyName And this part is the description`
 
---------------------------------------
+You can also optionally provide a type for the parameter.
+* `@response {String} MyName And this part is the description`
 
-You can use the `@query` tag as many times as you have parameters in your request url you whish to document.
+You can also specify that the response is optional by placing the name within square brackets.
+* `@response {String} [MyName] And this part is the description`
 
+Lastly you can define a default value for the parameter.
+* `@response {String} [MyName=Phillip] And this part is the description`
+
+
+```
+/**
+ * Download files.
+ *
+ * @name Download Files
+ * @path {GET} /v1/files
+ * @response {Object} metadata
+ * @response {String} metadata.name
+ * @response {String} metadata.limk
+ */
+server.get({
+  url: '/v1/files',
+}, (req, res, next) => {...}
+```
+
+The above would add a table under the route description that lists that the route answer with a json document containing the `name` and `link` key.
+
+You can use the `@response` tag as many times as you have parameters in your response you whish to document.
+
+
+## @code
+
+The `@code` allows you to document the http response code that your route will make
+
+With this tag you need to provide the number like this
+* `@code {200} and then you document why this code is happening`
+
+```
+/**
+ * Download files.
+ *
+ * @name Download Files
+ * @path {GET} /v1/files
+ * @code {200} if the request is sucesfull
+ * @code {500} if the request fail because the database isn't accesible 
+ * @response {Object} metadata
+ * @response {String} metadata.name
+ * @response {String} metadata.limk
+ */
+server.get({
+  url: '/v1/files',
+}, (req, res, next) => {...}
+```
+
+The above would add a table under the route description that lists that the route answer with a json document containing the `name` and `link` key.
+
+You can use the `@response` tag as many times as you have parameters in your response you whish to document.
+
 ## Donations
@@ -363,0 +317,0 @@

No alert changes

Improved metrics

Total package byte prevSize

25258

increased by7.08%

Number of package files

15

increased by15.38%

Lines of code

345

increased by28.25%

Worsened metrics

Number of lines in readme file

331

decreased by-12.2%

No dependency changes