Skip to content

Commit 972a21a

Browse files
JaredCEJaredCE
committed
improve documentation around extended specifications
1 parent 9e69420 commit 972a21a

File tree

1 file changed

+76
-16
lines changed

1 file changed

+76
-16
lines changed

‎README.md‎

Lines changed: 76 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -79,26 +79,30 @@ Options:
7979

8080
| OpenAPI field | Serverless field |
8181
| --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
82-
| info.title | custom.documentation.title OR service |
83-
| info.description | custom.documentation.description OR blank string |
84-
| info.version | custom.documentation.version OR random v4 uuid if not provided |
85-
| info.termsOfService | custom.documentation.termsOfService |
82+
| info.title | `custom.documentation.title` OR service |
83+
| info.description | `custom.documentation.description` OR blank string |
84+
| info.version | `custom.documentation.version` OR random v4 uuid if not provided |
85+
| info.termsOfService | `custom.documentation.termsOfService` |
8686
| info.contact | custom.documentation.contact |
87-
| info.contact.name | custom.documentation.contact.name OR blank string |
88-
| info.contact.url | custom.documentation.contact.url if provided |
87+
| info.contact.name | `custom.documentation.contact.name` OR blank string |
88+
| info.contact.url | `custom.documentation.contact.url` if provided |
89+
| info.contact.x- | `custom.documentation.contact.x-` extended specifications provided |
8990
| info.license | custom.documentation.license |
90-
| info.license.name | custom.documentation.license.name OR blank string |
91-
| info.license.url | custom.documentation.license.url if provided |
92-
| externalDocs.description | custom.documentation.externalDocumentation.description |
93-
| externalDocs.url | custom.documentation.externalDocumentation.url |
94-
| security | custom.documentation.security |
91+
| info.license.name | `custom.documentation.license.name` OR blank string |
92+
| info.license.url | `custom.documentation.license.url` if provided |
93+
| info.license.x- | `custom.documentation.license.x-` if extended specifications provided provided |
94+
| externalDocs.description | `custom.documentation.externalDocumentation.description ` |
95+
| externalDocs.url | `custom.documentation.externalDocumentation.url` |
96+
| x-tagGroups | `custom.documentation.x-tagGroups` if provided |
97+
| security | `custom.documentation.security` |
9598
| servers[].description | custom.documentation.servers.description |
9699
| servers[].url | custom.documentation.servers.url |
97100
| servers[].variables | custom.documentation.servers.variables |
98-
| tags[].name | custom.documentation.tags.name |
99-
| tags[].description | custom.documentation.tags.description |
100-
| tags[].externalDocs.url | custom.documentation.tags.externalDocumentation.url |
101-
| tags[].externalDocs.description | custom.documentation.tags.externalDocumentation.description |
101+
| tags[].name | `custom.documentation.tags.name` |
102+
| tags[].description | `custom.documentation.tags.description` |
103+
| tags[].externalDocs.url | `custom.documentation.tags.externalDocumentation.url` |
104+
| tags[].externalDocs.description | `custom.documentation.tags.externalDocumentation.description` |
105+
| tags[].externalDocs.x- | `custom.documentation.tags.externalDocumentation.x-` if extended specifications provided |
102106
| path[path] | functions.functions.events.[http OR httpApi].path |
103107
| path[path].servers[].description | functions.functions.servers.description |
104108
| path[path].servers[].url | functions.functions.servers.url |
@@ -189,7 +193,9 @@ custom:
189193
email: [email protected]
190194
```
191195

192-
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.
196+
These fields are optional, though `url` needs to in the form of a URL and `email` needs 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)).
197+
198+
This can be extended using the `^x-` specification extension.
193199

194200
#### License
195201

@@ -205,6 +211,8 @@ custom:
205211

206212
Name is required but `url` is optional and must be in the format of a url.
207213

214+
This can be extended using the `^x-` specification extension.
215+
208216
#### Extended Fields
209217

210218
You can also add extended fields to the documentation object:
@@ -225,6 +233,58 @@ custom:
225233

226234
`other-field` here will not make it to the generated OpenAPI schema.
227235

236+
Currently extended specification fields defined under the `documentation` tag will sit under the OpenAPI `info` object e.g.
237+
238+
```yml
239+
custom:
240+
documentation:
241+
title: myService
242+
x-other-field: This is an extended field
243+
```
244+
245+
converts to:
246+
247+
```json
248+
{
249+
"info": {
250+
"title": "myService",
251+
"x-other-field": "This is an extended field"
252+
}
253+
}
254+
```
255+
256+
An exception to this is Redocly `x-tagGroups`. If defined, they will sit at the root level of the OpenAPI specification, e.g.
257+
258+
```yml
259+
custom:
260+
documentation:
261+
title: myService
262+
x-other-field: This is an extended field
263+
x-tagGroups:
264+
- name: Customers
265+
tags:
266+
- Customers
267+
```
268+
269+
converts to:
270+
271+
```json
272+
{
273+
"info": {
274+
"title": "myService",
275+
"x-other-field": "This is an extended field"
276+
},
277+
"x-tagGroups": [
278+
{
279+
"name": "Customers",
280+
"tags": ["Customers"]
281+
}
282+
]
283+
}
284+
```
285+
286+
#### Moving documentation to a separate file
287+
228288
These configurations can be quite verbose; you can separate it out into it's own file, such as `serverless.doc.yml` as below:
229289

230290
```yml

0 commit comments

Comments
 (0)