serverless-openapi-documenter 0.0.26 → 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
@@ -354,9 +406,9 @@ cookieParams:
 
 Request Headers 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 header
+* `description`: a description of the header
+* `required`: whether the header is mandatory (boolean)
 * `schema`: JSON schema (inline, file or externally hosted)
 
 ```yml

package/package.json

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