1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
|
# OpenAPI
[OpenAPI][1] is a document that describes an API. It contains:
* at least one [paths][2] field.
* a [components][3] field or a [webhooks][4] field.
Media types should conform to [RFC-6838][5].
HTTP Status codes should follow [RFC-7231][6] and [IANA][7].
## Format
The document is a JSON file called `openapi.json`.
```json
{
"field": [1, 2, 3]
}
```
* field names are case sensitive
* fields can be:
* Fixed fields: have a declared name
* Patterned fields: declare a regex pattern for the field name
Data Types
| type | format |
| ------- | -------- |
| integer | int32 |
| integer | int64 |
| number | float |
| number | double |
| string | password |
Description fields can be written in [CommonMark][8] markdown.
Minimal example:
```json
{
"openapi": "3.1.0",
"info": {
"title": "xlg API",
"version": "0.1.0"
},
"servers": [
{
"url": "https://dev.xlg.c0/v0",
"description": "dev api"
}
],
"paths": {
"/health": {
"get": {
"responses": {
"200": {
"description": "Healthy",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"status"
],
"properties": {
"status": {
"type": "string"
}
}
}
}
}
}
}
}
}
},
"security": {
"type": "openIdConnect",
"openIdConnectUrl": "https://xlg.auth0.com/.well-known/openid-configuration"
}
}
```
[1]: https://spec.openapis.org/oas/v3.1.0#openapi-document
[2]: https://spec.openapis.org/oas/v3.1.0#pathsObject
[3]: https://spec.openapis.org/oas/v3.1.0#oasComponents
[4]: https://spec.openapis.org/oas/v3.1.0#oasWebhooks
[5]: https://www.rfc-editor.org/rfc/rfc6838.txt
[6]: https://www.rfc-editor.org/rfc/rfc7231.txt
[7]: https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml
[8]: https://spec.commonmark.org/0.30/
|
