/
spec.yaml
144 lines (130 loc) · 4.07 KB
/
spec.yaml
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
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
extends: spectral:oas
rules:
info-contact: off
operation-operationId: off
api-root:
description: API SHOULD have a root path defined (`/`)
recommended: true
severity: warn
given: $.paths
then:
field: /
function: truthy
api-root-get:
description: Root path MUST have a GET defined, otherwise people won't know how to get it
recommended: true
severity: error
given: $.paths[/]
then:
field: get
function: truthy
paths-kebab-case:
description: Paths MUST be kebab-case
recommended: true
message: '{{property}} should be kebab-case'
severity: error
given: $.paths[*]~
then:
function: pattern
functionOptions:
match: "^\/([a-z0-9]+(-[a-z0-9]+)*)?(\/[a-z0-9]+(-[a-z0-9]+)*|\/{.+})*$"
path-parameters-camelCase:
description: Path parameters MUST be camelCase
recommended: true
severity: error
message: "{{property}} path parameter is not camelCase: {{error}}"
given: $..parameters[?(@.in == 'path')].name
then:
function: pattern
functionOptions:
match: "^[a-z][a-zA-Z0-9]+$"
operation-summary:
description: Operation summary MUST exist
recommended: true
severity: error
given: $.paths.*[*]
then:
- field: summary
function: truthy
operation-short-summary:
description: Operation summary SHOULD be short and sweet, no full stops, less than 30 characters
recommended: true
severity: warn
given: $.paths.*[*]
then:
- field: summary
function: pattern
functionOptions:
notMatch: '\\.'
- field: summary
function: length
functionOptions:
max: 30
schema-names-pascal-case:
description: Schema names MUST be written in PascalCase
recommended: true
message: '{{property}} is not PascalCase: {{error}}'
given: '$.components.schemas.*~'
then:
function: pattern
functionOptions:
match: '^[A-Z][a-zA-Z0-9]*$'
semver:
description: API version MUST follow semantic versioning
recommended: true
severity: error
message: 'Please follow semantic versioning. {{value}} is not a valid version.'
given: $.info.version
then:
function: pattern
functionOptions:
match: '^([0-9]+.[0-9]+.[0-9]+)$'
no-x-headers:
description: Header MUST not be prefixed wit X- (https://tools.ietf.org/html/rfc6648)
recommended: true
severity: warn
message: "Headers MUST not be prefixed with X-. Please find a new name for {{property}}"
given: $..parameters.[?(@.in === 'header')].name
then:
function: pattern
functionOptions:
notMatch: '^(x|X)-'
headers-hyphenated-pascal-case:
description: All HTTP headers MUST use Hyphenated-Pascal-Case notation
recommended: true
severity: error
message: "'HTTP' headers MUST follow 'Hyphenated-Pascal-Case' notation"
given: $..parameters[?(@.in == 'header')].name
then:
function: pattern
functionOptions:
match: '/^([A-Z][a-z0-9]-)*([A-Z][a-z0-9])+/'
request-get-no-body:
description: A GET request MUST NOT accept a body parameter
recommended: true
severity: error
given: $.paths..get.parameters..in
then:
function: pattern
functionOptions:
notMatch: '/^body$/'
request-support-json:
description: Every request MUST support `application/json` media type
recommended: true
severity: error
message: "{{description}}: {{error}}"
given: $.paths.[*].requestBody.content[?(@property.indexOf('json') === -1)]^
then:
function: falsy
response-success-media-type:
description: All success responses MUST be of media type `application/hal+json` or `application/json`
recommended: true
severity: error
message: "Response documents MUST be of application/hal+json or application/json media types: {{error}}"
given: $.paths..responses[?( @property == 200 )].content[*]~
then:
function: enumeration
functionOptions:
values:
- application/json
- application/hal+json