serverless-openapi-documenter 0.0.11 → 0.0.15

package/README.md

@@ -15,13 +15,13 @@ Originally based off of: https://github.com/temando/serverless-openapi-documenta
 
 ## Install
 
-This plugin works for Serverless 2.x and up.
+This plugin works for Serverless 2.x and up and only supports node.js 14 and up.
 
 To add this plugin to your package.json:
 
 **Using npm:**
 ```bash
-npm install --save-dev serverless-openapi-documenter 
+npm install --save-dev serverless-openapi-documenter
 ```
 
 Next you need to add the plugin to the `plugins` section of your `serverless.yml` file.
@@ -112,7 +112,6 @@ custom:
     version: '1'
     title: 'My API'
     description: 'This is my API'
-    models: {}
     externalDocumentation:
       url: https://google.com
       description: A link to google
@@ -125,8 +124,11 @@ custom:
         externalDocumentation:
           url: https://npmjs.com
           description: A link to npm
+    models: {}
 ```
 
+Mostly everything here is optional.  A version from a UUID will be generated for you if you don't specify one, title will be the name of your service if you don't specify one.
+
 These configurations can be quite verbose; you can separate it out into it's own file, such as `serverless.doc.yml` as below:
 
 ```yml
@@ -146,9 +148,10 @@ For more info on `serverless.yml` syntax, see their docs.
 
 #### Models
 
-Models contain additional information that you can use to define schemas for endpoints.  You must define the *content type* for each schema that you provide in the models.
+There are two ways to write the Models.  Models contain additional information that you can use to define schemas for endpoints.  You must define the *content type* for each schema that you provide in the models.
 
-The *required* directives for the models section are as follow:
+The first way of writing the model is:
+*required* directives for the models section are as follow:
 
 * `name`: the name of the schema
 * `description`: a description of the schema
@@ -180,6 +183,40 @@ custom:
                   type: "string"
 ```
 
+The Second way of writing the models:
+
+* `name`: the name of the schema
+* `description`: a description of the schema
+* `content`: an Object made up of the contentType and the schema, as shown below
+
+```yml
+custom:
+  documentation:
+    models:
+      - name: "ErrorResponse"
+        description: "This is an error"
+        content:
+          application/json:
+            schema: ${file(models/ErrorResponse.json)}
+      - name: "PutDocumentResponse"
+        description: "PUT Document response model (external reference example)"
+        content:
+          application/json:
+            schema: ${file(models/PutDocumentResponse.json)}
+      - name: "PutDocumentRequest"
+        description: "PUT Document request model (inline example)"
+        content:
+          application/json:
+            schema:
+              $schema: "http://json-schema.org/draft-04/schema#"
+              properties:
+                SomeObject:
+                  type: "object"
+                  properties:
+                    SomeAttribute:
+                      type: "string"
+```
+
 #### 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.
@@ -206,11 +243,12 @@ The `documentation` section of the event configuration can contain the following
 ```yml
 functions:
   createUser:
-    handler: "handler.create"
+    handler: handler.create
     events:
       - http:
-        path: "create"
-        method: "post"
+        path: create
+        method: post
+        summary:
         documentation:
           summary: "Create User"
           description: "Creates a user and then sends a generated password email"
@@ -375,7 +413,7 @@ Please view the example [serverless.yml](test/serverless\ 2/serverless.yml).
 
 ## Notes on schemas
 
-Schemas can be either: inline, in file or externally hosted.  If they're inline or in file, the plugin will attempt to normalise the schema to [OpenAPI 3.0.X specification](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#schemaObject).  
+Schemas can be either: inline, in file or externally hosted.  If they're inline or in file, the plugin will attempt to normalise the schema to [OpenAPI 3.0.X specification](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#schemaObject).
 
 If they exist as an external reference, for instance:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "serverless-openapi-documenter",
-  "version": "0.0.11",
+  "version": "0.0.15",
   "description": "Generate OpenAPI v3 documentation and Postman Collections from your Serverless Config",
   "main": "index.js",
   "keywords": [
@@ -31,7 +31,7 @@
     "@apidevtools/json-schema-ref-parser": "^9.0.9",
     "chalk": "^4.1.2",
     "js-yaml": "^4.1.0",
-    "json-schema-for-openapi": "^0.1.4",
+    "json-schema-for-openapi": "^0.1.5",
     "oas-validator": "^5.0.8",
     "openapi-to-postmanv2": "^3.2.0",
     "swagger2openapi": "^7.0.8",

package/src/definitionGenerator.js

@@ -33,7 +33,7 @@ class DefinitionGenerator {
         } catch (err) {
             this.refParserOptions = {}
         }
-        
+
     }
 
     async parse() {
@@ -42,7 +42,7 @@ class DefinitionGenerator {
             .catch(err => {
                 throw err
             })
-        
+
         if (this.serverless.service.custom.documentation.servers) {
             const servers = this.createServers(this.serverless.service.custom.documentation.servers)
             Object.assign(this.openAPI, {servers: servers})
@@ -73,11 +73,10 @@ class DefinitionGenerator {
     async createPaths() {
         const paths = {}
         const httpFunctions = this.getHTTPFunctions()
-
         for (const httpFunction of httpFunctions) {
             for (const event of httpFunction.event) {
                 if (event?.http?.documentation || event?.httpApi?.documentation) {
-                    const documentation = event.http.documentation || event.httpApi.documentation
+                    const documentation = event?.http?.documentation || event?.httpApi?.documentation
 
                     let opId
                     if (this.operationIds.includes(httpFunction.functionInfo.name) === false) {
@@ -87,11 +86,11 @@ class DefinitionGenerator {
                         opId = `${httpFunction.functionInfo.name}-${uuid()}`
                     }
 
-                    const path = await this.createOperationObject(event.http.method || event.httpApi.method, documentation, opId)
+                    const path = await this.createOperationObject(event?.http?.method || event?.httpApi?.method, documentation, opId)
                         .catch(err => {
                             throw err
                         })
-                    
+
                     if (httpFunction.functionInfo?.summary)
                         path.summary = httpFunction.functionInfo.summary
 
@@ -103,10 +102,10 @@ class DefinitionGenerator {
                         path.servers = servers
                     }
 
-                    let slashPath = event.http.path
+                    let slashPath = event?.http?.path || event.httpApi?.path
                     const pathStart = new RegExp(/^\//, 'g')
                     if (pathStart.test(slashPath) === false) {
-                        slashPath = `/${event.http.path}`
+                        slashPath = `/${event?.http?.path||event.httpApi?.path}`
                     }
 
                     Object.assign(paths, {[slashPath]: path})
@@ -152,7 +151,7 @@ class DefinitionGenerator {
         // const documentation = this.serverless.service.custom.documentation
         // if (documentation.externalDocumentation) {
         //     // Object.assign(this.openAPI, {externalDocs: {...documentation.externalDocumentation}})
-        //     return 
+        //     return
         // }
     }
 
@@ -240,7 +239,7 @@ class DefinitionGenerator {
             obj.servers = servers
         }
 
-        return {[method]: obj}
+        return {[method.toLowerCase()]: obj}
     }
 
     async createResponses(documentation) {
@@ -292,14 +291,19 @@ class DefinitionGenerator {
                 if (mediaTypeDocumentation.examples)
                     obj.examples = this.createExamples(mediaTypeDocumentation.examples)
 
-                if (mediaTypeDocumentation.content[contentKey].schema) {
-                    const schemaRef = await this.schemaCreator(mediaTypeDocumentation.content[contentKey].schema, mediaTypeDocumentation.name)
-                        .catch(err => {
-                            throw err
-                        })
-                    obj.schema = {
-                        $ref: schemaRef
-                    }
+                let schema
+                if (mediaTypeDocumentation?.content) {
+                    schema = mediaTypeDocumentation.content[contentKey].schema
+                } else if (mediaTypeDocumentation?.contentType && mediaTypeDocumentation.schema) {
+                    schema = mediaTypeDocumentation.schema
+                }
+
+                const schemaRef = await this.schemaCreator(schema, mediaTypeDocumentation.name)
+                    .catch(err => {
+                        throw err
+                    })
+                obj.schema = {
+                    $ref: schemaRef
                 }
 
                 Object.assign(mediaTypeObj, {[contentKey]: obj})

package/src/openAPIGenerator.js

@@ -83,10 +83,17 @@ class OpenAPIGenerator {
         })
     }
 
-    log(type = this.defaultLog, ...str) {
+    log(type = this.defaultLog, str) {
         switch(this.serverless.version[0]) {
           case '2':
-            this.serverless.cli.log(str)
+            let colouredString = str
+            if (type === 'error') {
+              colouredString = chalk.bold.red(`✖ ${str}`)
+            } else if (type === 'success') {
+              colouredString = chalk.bold.green(`✓ ${str}`)
+            }
+
+            this.serverless.cli.log(colouredString)
             break
 
           case '3':
@@ -106,32 +113,32 @@ class OpenAPIGenerator {
 
         await generator.parse()
           .catch(err => {
-            this.log('error', chalk.bold.red(`ERROR: An error was thrown generating the OpenAPI v3 documentation`))
+            this.log('error', `ERROR: An error was thrown generating the OpenAPI v3 documentation`)
             throw new this.serverless.classes.Error(err)
           })
 
         const valid = await generator.validate()
           .catch(err => {
-            this.log('error', chalk.bold.red(`ERROR: An error was thrown validating the OpenAPI v3 documentation`))
+            this.log('error', `ERROR: An error was thrown validating the OpenAPI v3 documentation`)
             throw new this.serverless.classes.Error(err)
           })
 
         if (valid)
-          this.log(this.defaultLog, chalk.bold.green('OpenAPI v3 Documentation Successfully Generated'))
+          this.log('success', 'OpenAPI v3 Documentation Successfully Generated')
 
         if (config.postmanCollection) {
           const postmanGeneration = (err, result) => {
             if (err) {
-              this.log('error', chalk.bold.red(`ERROR: An error was thrown when generating the postman collection`))
+              this.log('error', `ERROR: An error was thrown when generating the postman collection`)
               throw new this.serverless.classes.Error(err)
             }
 
-            this.log(this.defaultLog, chalk.bold.green('postman collection v2 Documentation Successfully Generated'))
+            this.log('success', 'postman collection v2 Documentation Successfully Generated')
             try {
               fs.writeFileSync(config.postmanCollection, JSON.stringify(result.output[0].data))
-              this.log(this.defaultLog, chalk.bold.green('postman collection v2 Documentation Successfully Written'))
+              this.log('success', 'postman collection v2 Documentation Successfully Written')
             } catch (err) {
-              this.log('error', chalk.bold.red(`ERROR: An error was thrown whilst writing the postman collection`))
+              this.log('error', `ERROR: An error was thrown whilst writing the postman collection`)
               throw new this.serverless.classes.Error(err)
             }
           }
@@ -155,9 +162,9 @@ class OpenAPIGenerator {
         }
         try {
           fs.writeFileSync(config.file, output);
-          this.log(this.defaultLog, chalk.bold.green('OpenAPI v3 Documentation Successfully Written'))
+          this.log('success', 'OpenAPI v3 Documentation Successfully Written')
         } catch (err) {
-          this.log('error', chalk.bold.red(`ERROR: An error was thrown whilst writing the openAPI Documentation`))
+          this.log('error', `ERROR: An error was thrown whilst writing the openAPI Documentation`)
           throw new this.serverless.classes.Error(err)
         }
     }
@@ -177,7 +184,8 @@ class OpenAPIGenerator {
       config.postmanCollection = this.serverless.processedInput.options.postmanCollection || null
 
       if (['yaml', 'json'].indexOf(config.format.toLowerCase()) < 0) {
-        throw new Error('Invalid Output Format Specified - must be one of "yaml" or "json"');
+        // throw new Error('Invalid Output Format Specified - must be one of "yaml" or "json"');
+        throw new this.serverless.classes.Error('Invalid Output Format Specified - must be one of "yaml" or "json"')
       }
 
       config.file = this.serverless.processedInput.options.output ||
@@ -185,12 +193,12 @@ class OpenAPIGenerator {
 
       this.log(
         this.defaultLog,
-        `${chalk.bold.green('[OPTIONS]')}`,
-        ` openApiVersion: "${chalk.bold.red(String(config.openApiVersion))}"`,
-        ` format: "${chalk.bold.red(config.format)}"`,
-        ` output file: "${chalk.bold.red(config.file)}"`,
-        ` indentation: "${chalk.bold.red(String(config.indent))}"`,
-        ` ${config.postmanCollection ? `postman collection: ${chalk.bold.red(config.postmanCollection)}`: `\n\n`}`
+        `${chalk.bold.green('[OPTIONS]')}
+  openApiVersion: "${chalk.bold.green(String(config.openApiVersion))}"
+  format: "${chalk.bold.green(config.format)}"
+  output file: "${chalk.bold.green(config.file)}"
+  indentation: "${chalk.bold.green(String(config.indent))}"
+  ${config.postmanCollection ? `postman collection: ${chalk.bold.green(config.postmanCollection)}`: `\n\n`}`
       )
 
       return config

package/test/serverless 2/serverless.yml

@@ -19,7 +19,7 @@ functions:
           documentation:
             summary: Create User
             description: Creates a user and then sends a generated password email
-            tags: 
+            tags:
               - jesus
             externalDocumentation:
               url: https://bing.com
@@ -64,12 +64,28 @@ functions:
       - http:
           path: delete
           method: delete
-
+  patchUser:
+    handler: handler.patch
+    events:
+      - httpApi:
+          path: /patch/
+          method: PATCH
+          documentation:
+            summary: Patch a User
+            description: Patch details about the user
+            tags:
+              - patching
+            methodResponses:
+              - statusCode: 200
+                responseBody:
+                  description: A user object along with generated API Keys
+                responseModels:
+                  application/json: PutDocumentResponse
 custom:
   documentation:
     description: This is a description of what this does
     version: 1.0.0
-    tags: 
+    tags:
       - name: jesus
         description: jesus was a man
         externalDocumentation:

package/test/serverless 3/serverless.yml

@@ -12,11 +12,16 @@ functions:
     handler: handler.create
     events:
       - http:
-          path: create
+          path: create/{username}
           method: post
           documentation:
             summary: Create User
             description: Creates a user and then sends a generated password email
+            tags:
+              - jesus
+            externalDocumentation:
+              url: https://bing.com
+              description: A link to bing
             requestBody:
               description: A user information object
             requestModels:
@@ -54,25 +59,30 @@ functions:
 
 custom:
   documentation:
+    description: This is a description of what this does
+    version: 1.0.0
     models:
       - name: ErrorResponse
         description: This is an error
-        contentType: application/json
-        schema: ${file(models/ErrorResponse.json)}
+        content:
+          application/json:
+            schema: ${file(../models/ErrorResponse.json)}
 
       - name: PutDocumentResponse
         description: PUT Document response model (external reference example)
-        contentType: application/json
-        schema: ${file(models/PutDocumentResponse.json)}
+        content:
+          application/json:
+            schema: ${file(../models/PutDocumentResponse.json)}
 
       - name: PutDocumentRequest
         description: PUT Document request model (inline example)
-        contentType: application/json
-        schema:
-          $schema: http://json-schema.org/draft-04/schema#
-          properties:
-            SomeObject:
-              type: object
+        content:
+          application/json:
+            schema:
+              $schema: http://json-schema.org/draft-04/schema#
               properties:
-                SomeAttribute:
-                  type: string
+                SomeObject:
+                  type: object
+                  properties:
+                    SomeAttribute:
+                      type: string