serverless-openapi-documenter 0.0.30 → 0.0.32

package/README.md

@@ -59,6 +59,13 @@ Options:
 | info.title               | custom.documentation.title  OR  service                                            |
 | info.description         | custom.documentation.description  OR  blank string                                 |
 | info.version             | custom.documentation.version  OR  random v4 uuid if not provided                   |
+| info.termsOfService      | custom.documentation.termsOfService                   |
+| info.contact             | custom.documentation.contact                                                     |
+| info.contact.name         | custom.documentation.contact.name OR  blank string                                 |
+| info.contact.url          | custom.documentation.contact.url  if provided                           |
+| info.license             | custom.documentation.license                                                     |
+| info.license.name         | custom.documentation.license.name OR  blank string                                 |
+| info.license.url          | custom.documentation.license.url  if provided                           |
 | externalDocs.description | custom.documentation.externalDocumentation.description                             |
 | externalDocs.url         | custom.documentation.externalDocumentation.url                                     |
 | servers[].description      | custom.documentation.servers.description                                         |
@@ -118,6 +125,7 @@ custom:
     version: '1'
     title: 'My API'
     description: 'This is my API'
+    termsOfService: https://google.com
     externalDocumentation:
       url: https://google.com
       description: A link to google
@@ -126,7 +134,7 @@ custom:
       description: The server
       variables:
         port:
-          enum: 
+          enum:
             - 4000
             - 3000
           default: 3000
@@ -142,6 +150,58 @@ custom:
 
 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.
 
+#### termsOfService
+
+Must be in the format of a url if included.
+
+#### Contact
+
+You can provide an optional contact object such as:
+
+```yml
+custom:
+  documentation:
+    contact:
+      name: John
+      url: https://example.com
+      email: John@example.com
+```
+
+These fields are optional, though `url` and `email` need to be in the format of an email address (ed: what that might be, i'm not 100% sure... go read the email RFC(s)) and a url.
+
+#### License
+
+You can provide an optional license object such as:
+
+```yml
+custom:
+  documentation:
+    license:
+      name: Apache 2.0
+      url: https://www.apache.org/licenses/LICENSE-2.0.html
+```
+
+Name is required but `url` is optional and must be in the format of a url.
+#### Extended Fields
+
+You can also add extended fields to the documentation object:
+
+```yml
+custom:
+  documentation:
+    x-other-field: This is an extended field
+```
+
+These fields must have `x-` before them, otherwise they will be ignored:
+
+```yml
+custom:
+  documentation:
+    other-field: This is an extended field
+```
+
+`other-field` here will not make it to the generated OpenAPI schema.
+
 These configurations can be quite verbose; you can separate it out into it's own file, such as `serverless.doc.yml` as below:
 
 ```yml
@@ -246,16 +306,16 @@ custom:
             schema: &ErrorItem
             type: object
             properties:
-              message: 
+              message:
                 type: string
               code:
                 type: integer
-                  
+
       - name: "PutDocumentResponse"
         description: "PUT Document response model (external reference example)"
         content:
           application/json:
-            schema: 
+            schema:
             type: array
             items: *ErrorItem
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "serverless-openapi-documenter",
-  "version": "0.0.30",
+  "version": "0.0.32",
   "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.1.0",
     "chalk": "^4.1.2",
     "js-yaml": "^4.1.0",
-    "json-schema-for-openapi": "^0.3.0",
+    "json-schema-for-openapi": "^0.3.1",
     "oas-validator": "^5.0.8",
     "openapi-to-postmanv2": "^4.4.1",
     "swagger2openapi": "^7.0.8",

package/src/definitionGenerator.js

@@ -68,6 +68,37 @@ class DefinitionGenerator {
             description: documentation?.description || '',
             version: documentation?.version || uuid(),
         }
+
+        if (documentation.termsOfService)
+            info.termsOfService = documentation.termsOfService
+
+        if (documentation.contact) {
+            const contactObj = {}
+            contactObj.name = documentation.contact.name || ''
+
+            if (documentation.contact.url)
+                contactObj.url = documentation.contact.url
+
+            contactObj.email = documentation.contact.email || ''
+            Object.assign(info, {contact: contactObj})
+        }
+
+        if (documentation.license && documentation.license.name) {
+            const licenseObj = {}
+            licenseObj.name = documentation.license.name || ''
+
+            if (documentation.license.url)
+                licenseObj.url = documentation.license.url || ''
+
+            Object.assign(info, {license: licenseObj})
+        }
+
+        for (const key of Object.keys(documentation)) {
+            if (/^[x\-]/i.test(key)) {
+                Object.assign(info, {[key]: documentation[key]})
+            }
+        }
+
         Object.assign(this.openAPI, {info})
     }
 

package/test/unit/definitionGenerator.spec.js

@@ -174,6 +174,101 @@ describe('DefinitionGenerator', () => {
             expect(definitionGenerator.openAPI.info).to.be.an('object')
             expect(v4.test(definitionGenerator.openAPI.info.version)).to.be.true
         });
+
+        it('should assign a contact Object when a contact object is included', function() {
+            mockServerless.service.custom.documentation.contact = {
+                name: 'John',
+                url: 'http://example.com',
+                email: 'john@example.com'
+            }
+            const definitionGenerator = new DefinitionGenerator(mockServerless)
+            definitionGenerator.createInfo()
+
+            expect(definitionGenerator.openAPI).to.be.an('object')
+            expect(definitionGenerator.openAPI.info).to.be.an('object')
+            expect(definitionGenerator.openAPI.info).to.have.property('contact')
+            expect(definitionGenerator.openAPI.info.contact).to.be.an('object')
+            expect(definitionGenerator.openAPI.info.contact.name).to.be.an('string')
+        });
+
+        it('should only assign a contact url if one is provided', function() {
+            mockServerless.service.custom.documentation.contact = {
+                name: 'John',
+                email: 'john@example.com'
+            }
+            const definitionGenerator = new DefinitionGenerator(mockServerless)
+            definitionGenerator.createInfo()
+
+            expect(definitionGenerator.openAPI).to.be.an('object')
+            expect(definitionGenerator.openAPI.info).to.be.an('object')
+            expect(definitionGenerator.openAPI.info).to.have.property('contact')
+            expect(definitionGenerator.openAPI.info.contact).to.be.an('object')
+            expect(definitionGenerator.openAPI.info.contact.name).to.be.an('string')
+            expect(definitionGenerator.openAPI.info.contact).to.not.have.property('url')
+        });
+
+        it('should assign a license Object when a license object is included with a name', function() {
+            mockServerless.service.custom.documentation.license = {
+                name: 'Apache 2.0',
+                url: 'https://www.apache.org/licenses/LICENSE-2.0.html',
+            }
+            const definitionGenerator = new DefinitionGenerator(mockServerless)
+            definitionGenerator.createInfo()
+
+            expect(definitionGenerator.openAPI).to.be.an('object')
+            expect(definitionGenerator.openAPI.info).to.be.an('object')
+            expect(definitionGenerator.openAPI.info).to.have.property('license')
+            expect(definitionGenerator.openAPI.info.license).to.be.an('object')
+            expect(definitionGenerator.openAPI.info.license.name).to.be.an('string')
+        });
+
+        it('should not assign a license Object when a license object is included without a name', function() {
+            mockServerless.service.custom.documentation.license = {
+                url: 'https://www.apache.org/licenses/LICENSE-2.0.html',
+            }
+            const definitionGenerator = new DefinitionGenerator(mockServerless)
+            definitionGenerator.createInfo()
+
+            expect(definitionGenerator.openAPI).to.be.an('object')
+            expect(definitionGenerator.openAPI.info).to.be.an('object')
+            expect(definitionGenerator.openAPI.info).to.not.have.property('license')
+        });
+
+        it('should only assign a contact url if one is provided', function() {
+            mockServerless.service.custom.documentation.license = {
+                name: 'John',
+            }
+            const definitionGenerator = new DefinitionGenerator(mockServerless)
+            definitionGenerator.createInfo()
+
+            expect(definitionGenerator.openAPI).to.be.an('object')
+            expect(definitionGenerator.openAPI.info).to.be.an('object')
+            expect(definitionGenerator.openAPI.info).to.have.property('license')
+            expect(definitionGenerator.openAPI.info.license).to.be.an('object')
+            expect(definitionGenerator.openAPI.info.license.name).to.be.an('string')
+            expect(definitionGenerator.openAPI.info.license).to.not.have.property('url')
+        });
+
+        it('should assign specification extension fields when included', function() {
+            mockServerless.service.custom.documentation['x-field'] = 'john'
+            const definitionGenerator = new DefinitionGenerator(mockServerless)
+            definitionGenerator.createInfo()
+
+            expect(definitionGenerator.openAPI).to.be.an('object')
+            expect(definitionGenerator.openAPI.info).to.be.an('object')
+            expect(definitionGenerator.openAPI.info).to.have.property('x-field')
+            expect(definitionGenerator.openAPI.info['x-field']).to.be.equal('john')
+        });
+
+        it('should ignore fields that do not conform to specifiction extension', function() {
+            mockServerless.service.custom.documentation.otherField = 'john'
+            const definitionGenerator = new DefinitionGenerator(mockServerless)
+            definitionGenerator.createInfo()
+
+            expect(definitionGenerator.openAPI).to.be.an('object')
+            expect(definitionGenerator.openAPI.info).to.be.an('object')
+            expect(definitionGenerator.openAPI.info).to.not.have.property('otherField')
+        });
     });
 
     describe('createTags', () => {