serverless-openapi-documenter 0.0.3 → 0.0.4
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.
- package/README.md +45 -34
- package/package.json +1 -1
- package/src/definitionGenerator.js +14 -2
- package/test/serverless 2/serverless.yml +6 -0
package/README.md
CHANGED
|
@@ -40,40 +40,45 @@ Options:
|
|
|
40
40
|
|
|
41
41
|
### OpenAPI Mapping
|
|
42
42
|
|
|
43
|
-
| OpenAPI field
|
|
44
|
-
|
|
45
|
-
| info.title
|
|
46
|
-
| info.description
|
|
47
|
-
| info.version
|
|
48
|
-
|
|
|
49
|
-
|
|
|
50
|
-
| path[path]
|
|
51
|
-
| path[path].
|
|
52
|
-
| path[path].
|
|
53
|
-
| path[path].[operation]
|
|
54
|
-
| path[path].[operation].
|
|
55
|
-
| path[path].[operation].
|
|
56
|
-
| path[path].[operation].
|
|
57
|
-
| path[path].[operation].
|
|
58
|
-
| path[path].[operation].
|
|
59
|
-
| path[path].[operation].
|
|
60
|
-
| path[path].[operation].
|
|
61
|
-
| path[path].[operation].parameters
|
|
62
|
-
| path[path].[operation].parameters.
|
|
63
|
-
| path[path].[operation].parameters.
|
|
64
|
-
| path[path].[operation].parameters.
|
|
65
|
-
| path[path].[operation].parameters.
|
|
66
|
-
| path[path].[operation].parameters.
|
|
67
|
-
| path[path].[operation].parameters.
|
|
68
|
-
| path[path].[operation].parameters.
|
|
69
|
-
| path[path].[operation].
|
|
70
|
-
| path[path].[operation].
|
|
71
|
-
| path[path].[operation].
|
|
72
|
-
| path[path].[operation].
|
|
73
|
-
| path[path].[operation].
|
|
74
|
-
| path[path].[operation].requestBody
|
|
75
|
-
| path[path].[operation].requestBody.
|
|
76
|
-
| path[path].[operation].requestBody.
|
|
43
|
+
| OpenAPI field | Serverless field |
|
|
44
|
+
|--------------------------|------------------------------------------------------------------------------------|
|
|
45
|
+
| info.title | custom.documentation.title OR service |
|
|
46
|
+
| info.description | custom.documentation.description OR blank string |
|
|
47
|
+
| info.version | custom.documentation.version OR random v4 uuid if not provided |
|
|
48
|
+
| externalDocs.description | custom.documentation.externalDocumentation.description |
|
|
49
|
+
| externalDocs.url | custom.documenation.externalDocumentation.url |
|
|
50
|
+
| path[path] | functions.functions.events.[http OR httpApi].path |
|
|
51
|
+
| path[path].summary | functions.functions.summary |
|
|
52
|
+
| path[path].description | functions.functions.description |
|
|
53
|
+
| path[path].[operation] | functions.functions.[http OR httpApi].method |
|
|
54
|
+
| path[path].[operation].summary | functions.functions.[http OR httpApi].documentation.summary |
|
|
55
|
+
| path[path].[operation].description | functions.functions.[http OR httpApi].documentation.description |
|
|
56
|
+
| path[path].[operation].operationId | functions.functions.[http OR httpApi].documentation.operationId OR functionName |
|
|
57
|
+
| path[path].[operation].deprecated | functions.functions.[http OR httpApi].documentation.deprecated |
|
|
58
|
+
| path[path].[operation].externalDocs.description | functions.functions.[http OR httpApi].documentation.externalDocumentation.description |
|
|
59
|
+
| path[path].[operation].externalDocs.url | functions.functions.[http OR httpApi].documentation.externalDocumentation.url |
|
|
60
|
+
| path[path].[operation].deprecated | functions.functions.[http OR httpApi].documentation.deprecated |
|
|
61
|
+
| path[path].[operation].parameters | functions.functions.[http OR httpApi].documentation.[path|query|cookie|header]Params |
|
|
62
|
+
| path[path].[operation].parameters.name | functions.functions.[http OR httpApi].documentation.[path|query|cookie|header]Params.name |
|
|
63
|
+
| path[path].[operation].parameters.in | functions.functions.[http OR httpApi].documentation.[path|query|cookie|header]Params |
|
|
64
|
+
| path[path].[operation].parameters.description | functions.functions.[http OR httpApi].documentation.[path|query|cookie|header]Params.description |
|
|
65
|
+
| path[path].[operation].parameters.required | functions.functions.[http OR httpApi].documentation.[path|query|cookie|header]Params.required |
|
|
66
|
+
| path[path].[operation].parameters.deprecated | functions.functions.[http OR httpApi].documentation.[path|query|cookie|header]Params.deprecated |
|
|
67
|
+
| path[path].[operation].parameters.allowEmptyValue | functions.functions.[http OR httpApi].documentation.[path|query|cookie|header]Params.allowEmptyValue |
|
|
68
|
+
| path[path].[operation].parameters.style | functions.functions.[http OR httpApi].documentation.[path|query|cookie|header]Params.style |
|
|
69
|
+
| path[path].[operation].parameters.explode | functions.functions.[http OR httpApi].documentation.[path|query|cookie|header]Params.explode |
|
|
70
|
+
| path[path].[operation].parameters.allowReserved | functions.functions.[http OR httpApi].documentation.[path|query|cookie|header]Params.allowReserved |
|
|
71
|
+
| path[path].[operation].parameters.schema | functions.functions.[http OR httpApi].documentation.[path|query|cookie|header]Params.schema |
|
|
72
|
+
| path[path].[operation].parameters.example | functions.functions.[http OR httpApi].documentation.[path|query|cookie|header]Params.example |
|
|
73
|
+
| path[path].[operation].parameters.examples | functions.functions.[http OR httpApi].documentation.[path|query|cookie|header]Params.examples |
|
|
74
|
+
| path[path].[operation].requestBody | functions.functions.[http OR httpApi].documentation.requestBody |
|
|
75
|
+
| path[path].[operation].requestBody.description | functions.functions.[http OR httpApi].documentation.requestBody.description |
|
|
76
|
+
| path[path].[operation].requestBody.required | functions.functions.[http OR httpApi].documentation.requestBody.required |
|
|
77
|
+
| path[path].[operation].requestBody.content | functions.functions.[http OR httpApi].documentation.requestModels[contentType].name Links to custom.documentation.models.name |
|
|
78
|
+
| path[path].[operation].responses | functions.functions.[http OR httpApi].documentation.methodResponses |
|
|
79
|
+
| path[path].[operation].requestBody.[statusCode] | functions.functions.[http OR httpApi].documentation.methodResponses[statusCode] |
|
|
80
|
+
| path[path].[operation].requestBody.[statusCode].description | functions.functions.[http OR httpApi].documentation.methodResponses[statusCode].responseBody.description |
|
|
81
|
+
| path[path].[operation].requestBody.[statusCode].content | functions.functions.[http OR httpApi].documentation.methodResponses[statusCode].responseModels[contentType] Links to custom.documentation.models.name |
|
|
77
82
|
|
|
78
83
|
|
|
79
84
|
### Configuration
|
|
@@ -89,6 +94,9 @@ custom:
|
|
|
89
94
|
title: 'My API'
|
|
90
95
|
description: 'This is my API'
|
|
91
96
|
models: {}
|
|
97
|
+
externalDocumentation:
|
|
98
|
+
url: https://google.com
|
|
99
|
+
description: A link to google
|
|
92
100
|
```
|
|
93
101
|
|
|
94
102
|
These configurations can be quite verbose; you can separate it out into it's own file, such as `serverless.doc.yml` as below:
|
|
@@ -178,6 +186,9 @@ functions:
|
|
|
178
186
|
documentation:
|
|
179
187
|
summary: "Create User"
|
|
180
188
|
description: "Creates a user and then sends a generated password email"
|
|
189
|
+
externalDocumentation:
|
|
190
|
+
url: https://bing.com
|
|
191
|
+
description: A link to bing
|
|
181
192
|
requestBody:
|
|
182
193
|
description: "A user information object"
|
|
183
194
|
requestModels:
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "serverless-openapi-documenter",
|
|
3
|
-
"version": "0.0.
|
|
3
|
+
"version": "0.0.4",
|
|
4
4
|
"description": "Generate OpenAPI v3 documentation and Postman Collections from your Serverless Config",
|
|
5
5
|
"main": "index.js",
|
|
6
6
|
"keywords": ["serverless", "serverless2", "serverless3", "openAPI", "openAPIv3", "openAPI3", "PostmanCollections", "Postman-Collections"],
|
|
@@ -29,6 +29,7 @@ class DefinitionGenerator {
|
|
|
29
29
|
parse() {
|
|
30
30
|
this.createInfo()
|
|
31
31
|
this.createPaths()
|
|
32
|
+
this.createExternalDocumentation()
|
|
32
33
|
}
|
|
33
34
|
|
|
34
35
|
createInfo() {
|
|
@@ -36,7 +37,7 @@ class DefinitionGenerator {
|
|
|
36
37
|
const documentation = this.serverless.service.custom.documentation;
|
|
37
38
|
|
|
38
39
|
const info = {
|
|
39
|
-
title: service.service,
|
|
40
|
+
title: documentation?.title || service.service,
|
|
40
41
|
description: documentation?.description || '',
|
|
41
42
|
version: documentation?.version || uuid(),
|
|
42
43
|
}
|
|
@@ -80,6 +81,13 @@ class DefinitionGenerator {
|
|
|
80
81
|
Object.assign(this.openAPI, {paths})
|
|
81
82
|
}
|
|
82
83
|
|
|
84
|
+
createExternalDocumentation() {
|
|
85
|
+
const documentation = this.serverless.service.custom.documentation
|
|
86
|
+
if (documentation.externalDocumentation) {
|
|
87
|
+
Object.assign(this.openAPI, {externalDocs: {...documentation.externalDocumentation}})
|
|
88
|
+
}
|
|
89
|
+
}
|
|
90
|
+
|
|
83
91
|
createOperationObject(method, documentation, name = uuid()) {
|
|
84
92
|
const obj = {
|
|
85
93
|
summary: documentation.summary || '',
|
|
@@ -109,8 +117,12 @@ class DefinitionGenerator {
|
|
|
109
117
|
obj.parameters = obj.parameters.concat(paramObject)
|
|
110
118
|
}
|
|
111
119
|
|
|
120
|
+
if (documentation.externalDocumentation) {
|
|
121
|
+
obj.externalDocs = documentation.externalDocumentation
|
|
122
|
+
}
|
|
123
|
+
|
|
112
124
|
if (Object.keys(documentation).includes('deprecated'))
|
|
113
|
-
obj
|
|
125
|
+
obj.deprecated = documentation.deprecated
|
|
114
126
|
|
|
115
127
|
if (documentation.requestBody)
|
|
116
128
|
obj.requestBody = this.createRequestBody(documentation)
|
|
@@ -19,6 +19,9 @@ functions:
|
|
|
19
19
|
documentation:
|
|
20
20
|
summary: Create User
|
|
21
21
|
description: Creates a user and then sends a generated password email
|
|
22
|
+
externalDocumentation:
|
|
23
|
+
url: https://bing.com
|
|
24
|
+
description: A link to bing
|
|
22
25
|
requestBody:
|
|
23
26
|
description: A user information object
|
|
24
27
|
requestModels:
|
|
@@ -64,6 +67,9 @@ custom:
|
|
|
64
67
|
documentation:
|
|
65
68
|
description: This is a description of what this does
|
|
66
69
|
version: 1.0.0
|
|
70
|
+
externalDocumentation:
|
|
71
|
+
url: https://google.com
|
|
72
|
+
description: A link to google
|
|
67
73
|
models:
|
|
68
74
|
- name: ErrorResponse
|
|
69
75
|
description: This is an error
|