serverless-openapi-documenter 0.0.25 → 0.0.27

package/.github/workflows/node.yml

@@ -16,7 +16,7 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [14.x, 16.x]
+        node-version: [14.x, 16.x, 18.x]
         # See supported Node.js release schedule at https://nodejs.org/en/about/releases/
 
     steps:

package/README.md

@@ -63,6 +63,7 @@ Options:
 | externalDocs.url         | custom.documentation.externalDocumentation.url                                     |
 | servers[].description      | custom.documentation.servers.description                                         |
 | servers[].url              | custom.documentation.servers.url                                                 |
+| servers[].variables              | custom.documentation.servers.variables                                     |
 | tags[].name                     | custom.documentation.tags.name                                              |
 | tags[].description              | custom.documentation.tags.description                                       |
 | tags[].externalDocs.url         | custom.documentation.tags.externalDocumentation.url                         |
@@ -121,8 +122,15 @@ custom:
       url: https://google.com
       description: A link to google
     servers:
-      url: https://example.com
+      url: https://example.com:{port}/
       description: The server
+      variables:
+        port:
+          enum: 
+            - 4000
+            - 3000
+          default: 3000
+          description: The port the server operates on
     tags:
       - name: tag1
         description: this is a tag
@@ -222,6 +230,39 @@ custom:
                       type: "string"
 ```
 
+##### Model re-use
+
+Through the magic of YAML, you can re-use models:
+
+```yml
+custom:
+  documentation:
+    ...
+    models:
+      - name: "ErrorResponse"
+        description: "This is an error"
+        content:
+          application/json:
+            schema: &ErrorItem
+            type: object
+            properties:
+              message: 
+                type: string
+              code:
+                type: integer
+                  
+      - name: "PutDocumentResponse"
+        description: "PUT Document response model (external reference example)"
+        content:
+          application/json:
+            schema: 
+            type: array
+            items: *ErrorItem
+```
+
+`&ErrorItem` in the above example creates a node anchor (&ErrorItem) to the `ErrorResponse` schema which then can be used in the `PutDocumentResponse` schema via the reference (*ErrorItem).  The node anchor needs to be declared first before it can be used elsewhere via the reference, swapping the above example around would result in an error.
+
+
 #### Functions
 
 To define the documentation for a given function event, you need to create a `documentation` attribute for your http event in your `serverless.yml` file.
@@ -238,6 +279,7 @@ The `documentation` section of the event configuration can contain the following
 * `queryParams`: a list of query parameters (see [queryParams](#queryparams) below)
 * `pathParams`: a list of path parameters (see [pathParams](#pathparams) below)
 * `cookieParams`: a list of cookie parameters (see [cookieParams](#cookieparams) below)
+* `headerParams`: a list of headers (see [headerParams](#headerparams---request-headers) below)
 * `methodResponses`: an array of response models and applicable status codes
   * `statusCode`: applicable http status code (ie. 200/404/500 etc.)
   * `responseBody`: contains description of the response
@@ -285,12 +327,22 @@ functions:
               description: "A Session ID variable"
               schema:
                 type: "string"
+          headerParams:
+            name: "Content-Type"
+            description: "The content type"
+            schema:
+              type: "string"
           methodResponses:
             - statusCode: 201
               responseBody:
                 description: "A user object along with generated API Keys"
               responseModels:
                 application/json: "PutDocumentResponse"
+              responseHeaders:
+                X-Rate-Limit-Limit:
+                  description: The number of allowed requests in the current period
+                  schema:
+                    type: integer
             - statusCode: 500
               responseBody:
                 description: "An error message when creating a new user"
@@ -320,8 +372,8 @@ queryParams:
 
 Path parameters can be described as follow:
 
-* `name`: the name of the query variable
-* `description`: a description of the query variable
+* `name`: the name of the path parameter
+* `description`: a description of the path parameter
 * `schema`: JSON schema (inline, file or externally hosted)
 
 ```yml
@@ -336,9 +388,9 @@ pathParams:
 
 Cookie parameters can be described as follow:
 
-* `name`: the name of the query variable
-* `description`: a description of the query variable
-* `required`: whether the query parameter is mandatory (boolean)
+* `name`: the name of the cookie parameter
+* `description`: a description of the cookie parameter
+* `required`: whether the cookie parameter is mandatory (boolean)
 * `schema`: JSON schema (inline, file or externally hosted)
 
 ```yml
@@ -350,6 +402,24 @@ cookieParams:
       type: "string"
 ```
 
+#### `headerParams` - Request Headers
+
+Request Headers can be described as follow:
+
+* `name`: the name of the header
+* `description`: a description of the header
+* `required`: whether the header is mandatory (boolean)
+* `schema`: JSON schema (inline, file or externally hosted)
+
+```yml
+headerParams:
+  - name: "Content-Type"
+    description: "The content type"
+    required: true
+    schema:
+      type: "string"
+```
+
 #### `requestModels`
 
 The `requestModels` property allows you to define models for the HTTP Request of the function event. You can define a different model for each different `Content-Type`. You can define a reference to the relevant request model named in the `models` section of your configuration (see [Defining Models](#models) section).
@@ -369,14 +439,24 @@ For an example of a `methodResponses` configuration for an event see below:
 ```yml
 methodResponse:
   - statusCode: 200
-    responseHeaders:
-      - name: "Content-Type"
-        description: "Content Type header"
-        schema:
-          type: "string"
+    responseBody:
+      description: Success
     responseModels:
       application/json: "CreateResponse"
       application/xml: "CreateResponseXML"
+    responseHeaders:
+      X-Rate-Limit-Limit:
+        description: The number of allowed requests in the current period
+        schema:
+          type: integer
+      X-Rate-Limit-Remaining:
+        description: The number of remaining requests in the current period
+        schema:
+          type: integer
+      X-Rate-Limit-Reset:
+        description: The number of seconds left in the current period
+        schema:
+          type: integer
 ```
 
 ##### `responseModels`
@@ -389,27 +469,16 @@ responseModels:
   application/xml: "CreateResponseXML"
 ```
 
-##### `responseHeaders` and `requestHeaders`
-
-The `responseHeaders/requestHeaders` section of the configuration allows you to define the HTTP headers for the function event.
-
-The attributes for a header are as follow:
+##### `responseHeaders`
 
-* `name`: the name of the HTTP Header
-* `description`: a description of the HTTP Header
-* `schema`: JSON schema (inline, file or externally hosted)
+The `responseHeaders` property allows you to define the headers expected in a HTTP Response of the function event.  This should only contain a description and a schema, which must be a JSON schema (inline, file or externally hosted).
 
 ```yml
 responseHeaders:
-  - name: "Content-Type"
-    description: "Content Type header"
-    schema:
-      type: "string"
-requestHeaders:
-  - name: "Content-Type"
-    description: "Content Type header"
+  X-Rate-Limit-Limit:
+    description: The number of allowed requests in the current period
     schema:
-      type: "string"
+      type: integer
 ```
 
 ## Example configuration

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "serverless-openapi-documenter",
-  "version": "0.0.25",
+  "version": "0.0.27",
   "description": "Generate OpenAPI v3 documentation and Postman Collections from your Serverless Config",
   "main": "index.js",
   "keywords": [

package/src/definitionGenerator.js

@@ -271,12 +271,41 @@ class DefinitionGenerator {
                     throw err
                 })
 
+            if (response.responseHeaders) {
+                obj.headers = await this.createResponseHeaders(response.responseHeaders)
+                    .catch(err => {
+                        throw err
+                    })
+            }
+
             Object.assign(responses,{[response.statusCode]: obj})
         }
 
         return responses
     }
 
+    async createResponseHeaders(headers) {
+        const obj = {}
+        for (const header of Object.keys(headers)) {
+            const newHeader = {}
+            newHeader.description = headers[header].description || ''
+
+            if (headers[header].schema) {
+                const schemaRef = await this.schemaCreator(headers[header].schema, header)
+                    .catch(err => {
+                        throw err
+                    })
+                newHeader.schema = {
+                    $ref: schemaRef
+                }
+            }
+
+            Object.assign(obj, {[header]: newHeader})
+        }
+
+        return obj
+    }
+
     async createRequestBody(documentation) {
         const obj = {
             description: documentation.requestBody.description,