serverless-openapi-documenter 0.0.4 → 0.0.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +31 -1
  2. package/package.json +14 -5
  3. package/src/definitionGenerator.js +81 -6
  4. package/src/openAPIGenerator.js +10 -2
  5. package/test/serverless 2/serverless.yml +8 -0
package/README.md CHANGED
@@ -1,5 +1,14 @@
1
1
  # OpenAPI Generator for serverless
2
2
 
3
+ <p>
4
+ <a href="https://www.serverless.com">
5
+ <img src="http://public.serverless.com/badges/v3.svg">
6
+ </a>
7
+ <a href="https://www.npmjs.com/package/serverless-openapi-documenter">
8
+ <img src="https://img.shields.io/npm/v/serverless-openapi-documenter.svg?style=flat-square">
9
+ </a>
10
+ </p>
11
+
3
12
  This will generate an OpenAPI V3 (up to v3.0.3) file for you from your serverless file. It can optionally generate a Postman Collection V2 from the OpenAPI file for you too.
4
13
 
5
14
  Originally based off of: https://github.com/temando/serverless-openapi-documentation
@@ -46,10 +55,18 @@ Options:
46
55
  | info.description | custom.documentation.description OR blank string |
47
56
  | info.version | custom.documentation.version OR random v4 uuid if not provided |
48
57
  | externalDocs.description | custom.documentation.externalDocumentation.description |
49
- | externalDocs.url | custom.documenation.externalDocumentation.url |
58
+ | externalDocs.url | custom.documentation.externalDocumentation.url |
59
+ | servers[].description | custom.documentation.servers.description |
60
+ | servers[].url | custom.documentation.servers.url |
61
+ | tags[].name | custom.documentation.tags.name |
62
+ | tags[].description | custom.documentation.tags.description |
63
+ | tags[].externalDocs.url | custom.documentation.tags.externalDocumentation.url |
64
+ | tags[].externalDocs.description | custom.documentation.tags.externalDocumentation.description |
50
65
  | path[path] | functions.functions.events.[http OR httpApi].path |
51
66
  | path[path].summary | functions.functions.summary |
52
67
  | path[path].description | functions.functions.description |
68
+ | path[path].servers[].description | functions.functions.servers.description |
69
+ | path[path].servers[].url | functions.functions.servers.url |
53
70
  | path[path].[operation] | functions.functions.[http OR httpApi].method |
54
71
  | path[path].[operation].summary | functions.functions.[http OR httpApi].documentation.summary |
55
72
  | path[path].[operation].description | functions.functions.[http OR httpApi].documentation.description |
@@ -57,6 +74,8 @@ Options:
57
74
  | path[path].[operation].deprecated | functions.functions.[http OR httpApi].documentation.deprecated |
58
75
  | path[path].[operation].externalDocs.description | functions.functions.[http OR httpApi].documentation.externalDocumentation.description |
59
76
  | path[path].[operation].externalDocs.url | functions.functions.[http OR httpApi].documentation.externalDocumentation.url |
77
+ | path[path].[operation].servers[].description | functions.functions.[http OR httpApi].documentation.servers.description |
78
+ | path[path].[operation].servers[].url | functions.functions.[http OR httpApi].documentation.servers.url |
60
79
  | path[path].[operation].deprecated | functions.functions.[http OR httpApi].documentation.deprecated |
61
80
  | path[path].[operation].parameters | functions.functions.[http OR httpApi].documentation.[path|query|cookie|header]Params |
62
81
  | path[path].[operation].parameters.name | functions.functions.[http OR httpApi].documentation.[path|query|cookie|header]Params.name |
@@ -97,6 +116,15 @@ custom:
97
116
  externalDocumentation:
98
117
  url: https://google.com
99
118
  description: A link to google
119
+ servers:
120
+ url: https://example.com
121
+ description: The server
122
+ tags:
123
+ - name: tag1
124
+ description: this is a tag
125
+ externalDocumentation:
126
+ url: https://npmjs.com
127
+ description: A link to npm
100
128
  ```
101
129
 
102
130
  These configurations can be quite verbose; you can separate it out into it's own file, such as `serverless.doc.yml` as below:
@@ -186,6 +214,8 @@ functions:
186
214
  documentation:
187
215
  summary: "Create User"
188
216
  description: "Creates a user and then sends a generated password email"
217
+ tags:
218
+ - tag1
189
219
  externalDocumentation:
190
220
  url: https://bing.com
191
221
  description: A link to bing
package/package.json CHANGED
@@ -1,9 +1,18 @@
1
1
  {
2
2
  "name": "serverless-openapi-documenter",
3
- "version": "0.0.4",
3
+ "version": "0.0.7",
4
4
  "description": "Generate OpenAPI v3 documentation and Postman Collections from your Serverless Config",
5
5
  "main": "index.js",
6
- "keywords": ["serverless", "serverless2", "serverless3", "openAPI", "openAPIv3", "openAPI3", "PostmanCollections", "Postman-Collections"],
6
+ "keywords": [
7
+ "serverless",
8
+ "serverless2",
9
+ "serverless3",
10
+ "openAPI",
11
+ "openAPIv3",
12
+ "openAPI3",
13
+ "PostmanCollections",
14
+ "Postman-Collections"
15
+ ],
7
16
  "scripts": {
8
17
  "test": "echo \"Error: no test specified\" && exit 1"
9
18
  },
@@ -18,9 +27,6 @@
18
27
  "url": "https://github.com/JaredCE/serverless-openapi-documenter/issues"
19
28
  },
20
29
  "license": "MIT",
21
- "devDependencies": {
22
- "serverless": "^3.17.0"
23
- },
24
30
  "dependencies": {
25
31
  "chalk": "^4.1.2",
26
32
  "js-yaml": "^4.1.0",
@@ -29,5 +35,8 @@
29
35
  "openapi-to-postmanv2": "^3.2.0",
30
36
  "swagger2openapi": "^7.0.8",
31
37
  "uuid": "^8.3.2"
38
+ },
39
+ "engines": {
40
+ "node": ">=14"
32
41
  }
33
42
  }
package/src/definitionGenerator.js CHANGED
@@ -6,7 +6,7 @@ const SchemaConvertor = require('json-schema-for-openapi')
6
6
 
7
7
  class DefinitionGenerator {
8
8
  constructor(serverless, options = {}) {
9
- this.version = options.v || '3.0.0'
9
+ this.version = serverless.processedInput.options.openApiVersion || '3.0.0'
10
10
 
11
11
  this.serverless = serverless
12
12
  this.httpKeys = {
@@ -29,7 +29,20 @@ class DefinitionGenerator {
29
29
  parse() {
30
30
  this.createInfo()
31
31
  this.createPaths()
32
- this.createExternalDocumentation()
32
+
33
+ if (this.serverless.service.custom.documentation.servers) {
34
+ const servers = this.createServers(this.serverless.service.custom.documentation.servers)
35
+ Object.assign(this.openAPI, {servers: servers})
36
+ }
37
+
38
+ if (this.serverless.service.custom.documentation.tags) {
39
+ this.createTags()
40
+ }
41
+
42
+ if (this.serverless.service.custom.documentation.externalDocumentation) {
43
+ const extDoc = this.createExternalDocumentation(this.serverless.service.custom.documentation.externalDocumentation)
44
+ Object.assign(this.openAPI, {externalDocs: extDoc})
45
+ }
33
46
  }
34
47
 
35
48
  createInfo() {
@@ -68,6 +81,11 @@ class DefinitionGenerator {
68
81
  if (httpFunction.functionInfo?.description)
69
82
  path.description = httpFunction.functionInfo.description
70
83
 
84
+ if (httpFunction.functionInfo?.servers) {
85
+ const servers = this.createServers(httpFunction.functionInfo.servers)
86
+ path.servers = servers
87
+ }
88
+
71
89
  let slashPath = event.http.path
72
90
  const pathStart = new RegExp(/^\//, 'g')
73
91
  if (pathStart.test(slashPath) === false) {
@@ -81,11 +99,63 @@ class DefinitionGenerator {
81
99
  Object.assign(this.openAPI, {paths})
82
100
  }
83
101
 
84
- createExternalDocumentation() {
85
- const documentation = this.serverless.service.custom.documentation
86
- if (documentation.externalDocumentation) {
87
- Object.assign(this.openAPI, {externalDocs: {...documentation.externalDocumentation}})
102
+ createServers(servers) {
103
+ const serverDoc = servers
104
+ const newServers = []
105
+
106
+ if (Array.isArray(serverDoc)) {
107
+ for (const server of serverDoc) {
108
+ const obj = {
109
+ url: server.url,
110
+ }
111
+
112
+ if (server.description) {
113
+ obj.description = server.description
114
+ }
115
+
116
+ newServers.push(obj)
117
+ }
118
+ } else {
119
+ const obj = {
120
+ url: servers.url,
121
+ }
122
+
123
+ if (servers.description) {
124
+ obj.description = servers.description
125
+ }
126
+
127
+ newServers.push(obj)
128
+ }
129
+
130
+ return newServers
131
+ }
132
+
133
+ createExternalDocumentation(docs) {
134
+ return {...docs}
135
+ // const documentation = this.serverless.service.custom.documentation
136
+ // if (documentation.externalDocumentation) {
137
+ // // Object.assign(this.openAPI, {externalDocs: {...documentation.externalDocumentation}})
138
+ // return
139
+ // }
140
+ }
141
+
142
+ createTags() {
143
+ const tags = []
144
+ for (const tag of this.serverless.service.custom.documentation.tags) {
145
+ const obj = {
146
+ name: tag.name,
147
+ }
148
+
149
+ if (tag.description) {
150
+ obj.description = tag.description
151
+ }
152
+
153
+ if (tag.externalDocumentation) {
154
+ obj.externalDocs = this.createExternalDocumentation(tag.externalDocumentation)
155
+ }
156
+ tags.push(obj)
88
157
  }
158
+ Object.assign(this.openAPI, {tags: tags})
89
159
  }
90
160
 
91
161
  createOperationObject(method, documentation, name = uuid()) {
@@ -130,6 +200,11 @@ class DefinitionGenerator {
130
200
  if (documentation.methodResponses)
131
201
  obj.responses = this.createResponses(documentation)
132
202
 
203
+ if (documentation.servers) {
204
+ const servers = this.createServers(documentation.servers)
205
+ obj.servers = servers
206
+ }
207
+
133
208
  return {[method]: obj}
134
209
  }
135
210
 
package/src/openAPIGenerator.js CHANGED
@@ -67,10 +67,18 @@ class OpenAPIGenerator {
67
67
  required: ['documentation'],
68
68
  });
69
69
 
70
+ this.serverless.configSchemaHandler.defineFunctionEventProperties('aws', 'httpApi', {
71
+ properties: {
72
+ documentation: { type: 'object' },
73
+ },
74
+ required: ['documentation'],
75
+ });
76
+
70
77
  this.serverless.configSchemaHandler.defineFunctionProperties('aws', {
71
78
  properties: {
72
79
  // description: {type: 'string'},
73
- summary: {type: 'string'}
80
+ summary: {type: 'string'},
81
+ servers: {anyOf: [{type:'object'}, {type:'array'}]},
74
82
  }
75
83
  })
76
84
  }
@@ -126,7 +134,7 @@ class OpenAPIGenerator {
126
134
  }
127
135
 
128
136
  const postmanCollection = PostmanGenerator.convert(
129
- {type: 'json', data: generator.openAPI},
137
+ {type: 'json', data: JSON.parse(JSON.stringify(generator.openAPI))},
130
138
  {},
131
139
  postmanGeneration
132
140
  )
package/test/serverless 2/serverless.yml CHANGED
@@ -19,6 +19,8 @@ functions:
19
19
  documentation:
20
20
  summary: Create User
21
21
  description: Creates a user and then sends a generated password email
22
+ tags:
23
+ - jesus
22
24
  externalDocumentation:
23
25
  url: https://bing.com
24
26
  description: A link to bing
@@ -67,6 +69,12 @@ custom:
67
69
  documentation:
68
70
  description: This is a description of what this does
69
71
  version: 1.0.0
72
+ tags:
73
+ - name: jesus
74
+ description: jesus was a man
75
+ externalDocumentation:
76
+ url: https://whitehouse.gov
77
+ description: a link to the whitehouse
70
78
  externalDocumentation:
71
79
  url: https://google.com
72
80
  description: A link to google