serverless-openapi-documenter 0.0.6 → 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 +25 -4
  2. package/package.json +4 -1
  3. package/src/definitionGenerator.js +35 -5
  4. package/src/openAPIGenerator.js +7 -0
  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
@@ -47,13 +56,17 @@ Options:
47
56
  | info.version | custom.documentation.version OR random v4 uuid if not provided |
48
57
  | externalDocs.description | custom.documentation.externalDocumentation.description |
49
58
  | externalDocs.url | custom.documentation.externalDocumentation.url |
50
- | servers[].description | custom.documentation.servers.description |
51
- | servers[].url | custom.documentation.servers.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 |
52
65
  | path[path] | functions.functions.events.[http OR httpApi].path |
53
66
  | path[path].summary | functions.functions.summary |
54
67
  | path[path].description | functions.functions.description |
55
- | path[path].servers[].description | functions.functions.servers.description |
56
- | path[path].servers[].url | functions.functions.servers.url |
68
+ | path[path].servers[].description | functions.functions.servers.description |
69
+ | path[path].servers[].url | functions.functions.servers.url |
57
70
  | path[path].[operation] | functions.functions.[http OR httpApi].method |
58
71
  | path[path].[operation].summary | functions.functions.[http OR httpApi].documentation.summary |
59
72
  | path[path].[operation].description | functions.functions.[http OR httpApi].documentation.description |
@@ -106,6 +119,12 @@ custom:
106
119
  servers:
107
120
  url: https://example.com
108
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
109
128
  ```
110
129
 
111
130
  These configurations can be quite verbose; you can separate it out into it's own file, such as `serverless.doc.yml` as below:
@@ -195,6 +214,8 @@ functions:
195
214
  documentation:
196
215
  summary: "Create User"
197
216
  description: "Creates a user and then sends a generated password email"
217
+ tags:
218
+ - tag1
198
219
  externalDocumentation:
199
220
  url: https://bing.com
200
221
  description: A link to bing
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "serverless-openapi-documenter",
3
- "version": "0.0.6",
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
6
  "keywords": [
@@ -35,5 +35,8 @@
35
35
  "openapi-to-postmanv2": "^3.2.0",
36
36
  "swagger2openapi": "^7.0.8",
37
37
  "uuid": "^8.3.2"
38
+ },
39
+ "engines": {
40
+ "node": ">=14"
38
41
  }
39
42
  }
package/src/definitionGenerator.js CHANGED
@@ -29,11 +29,20 @@ class DefinitionGenerator {
29
29
  parse() {
30
30
  this.createInfo()
31
31
  this.createPaths()
32
+
32
33
  if (this.serverless.service.custom.documentation.servers) {
33
34
  const servers = this.createServers(this.serverless.service.custom.documentation.servers)
34
35
  Object.assign(this.openAPI, {servers: servers})
35
36
  }
36
- this.createExternalDocumentation()
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
+ }
37
46
  }
38
47
 
39
48
  createInfo() {
@@ -121,11 +130,32 @@ class DefinitionGenerator {
121
130
  return newServers
122
131
  }
123
132
 
124
- createExternalDocumentation() {
125
- const documentation = this.serverless.service.custom.documentation
126
- if (documentation.externalDocumentation) {
127
- Object.assign(this.openAPI, {externalDocs: {...documentation.externalDocumentation}})
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)
128
157
  }
158
+ Object.assign(this.openAPI, {tags: tags})
129
159
  }
130
160
 
131
161
  createOperationObject(method, documentation, name = uuid()) {
package/src/openAPIGenerator.js CHANGED
@@ -67,6 +67,13 @@ 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'},
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