serverless-openapi-documenter 0.0.60 → 0.0.62

package/README.md

@@ -389,6 +389,23 @@ custom:
 
 `&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.
 
+##### ModelsList - Backwards compatibility
+
+It was brought to my attention that an older plugin version allowed the use of `modelsList`.  As of 0.0.60, you can continue to use `modelsList` as well as using `models`, however `modelsList` now has to be nested within the `documentation` section.  You can write `modelsList` the same way as any of the two styles for [Models](#Models).
+
+```
+custom:
+  documentation:
+    ...
+    modelsList:
+      - name: "ErrorResponse"
+        description: "This is an error"
+        content:
+          application/json:
+            schema:
+              type: string
+```
+
 
 #### Functions
 
@@ -605,6 +622,46 @@ functions:
               - {}
 ```
 
+##### private
+
+If you use the [private](https://www.serverless.com/framework/docs/providers/aws/events/apigateway#setting-api-keys-for-your-rest-api) property on your event:
+
+```yml
+functions:
+  getData:
+    events:
+      - http:
+          path: /
+          method: get
+          private: true
+```
+
+It will automatically setup an apiKey security scheme of `x-api-key` attached to that method.  You don't need to add this to the [Security Scheme](#securityschemes) in the main documentation.  If you have already added a Security Scheme of an `apiKey` with a name of `x-api-key`, it will associate with that key.
+
+```yml
+custom:
+  documentation:
+    securitySchemes:
+      my_api_key:
+        type: apiKey
+        name: x-api-key
+        in: header
+    security:
+      - my_api_key: []
+
+functions:
+  getData:
+    events:
+      - http:
+          path: /
+          method: get
+          private: true
+          documentation:
+            ...
+```
+
+Will set the Security Scheme to `my_api_key` for that operation.
+
 #### `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).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "serverless-openapi-documenter",
-  "version": "0.0.60",
+  "version": "0.0.62",
   "description": "Generate OpenAPI v3 documentation and Postman Collections from your Serverless Config",
   "main": "index.js",
   "keywords": [
@@ -38,7 +38,7 @@
     "json-schema-for-openapi": "^0.3.2",
     "lodash.isequal": "^4.5.0",
     "oas-validator": "^5.0.8",
-    "openapi-to-postmanv2": "^4.12.0",
+    "openapi-to-postmanv2": "^4.13.0",
     "swagger2openapi": "^7.0.8",
     "uuid": "^9.0.0"
   },

package/src/definitionGenerator.js

@@ -312,6 +312,29 @@ class DefinitionGenerator {
             obj.security = documentation.security
         }
 
+        if (this.currentEvent?.private && this.currentEvent.private === true) {
+            let apiKeyName = 'x-api-key'
+            let hasXAPIKey = false
+            if (this.openAPI?.components?.[this.componentTypes.securitySchemes]) {
+                for (const [schemeName, schemeValue] of Object.entries(this.openAPI.components[this.componentTypes.securitySchemes])) {
+                    if (schemeValue.type === 'apiKey' && schemeValue.name === 'x-api-key') {
+                        apiKeyName = schemeName
+                        hasXAPIKey = true
+                    }
+                }
+            }
+
+            if (hasXAPIKey === false) {
+                this.createSecuritySchemes({[apiKeyName]: {type: 'apiKey', name: apiKeyName, in: 'header'}})
+            }
+
+            if (obj.security) {
+                obj.security.push({[apiKeyName]: []})
+            } else {
+                obj.security = [{[apiKeyName]: []}]
+            }
+        }
+
         if (Object.keys(documentation).includes('deprecated'))
             obj.deprecated = documentation.deprecated