shell/rules/shell-rules.yml at main · api-evangelist/shell · GitHub

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
extends: spectral:oas
rules:
  # Shell API Naming Conventions
  shell-operation-id-camel-case:
    description: Operation IDs must use camelCase
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete].operationId"
    then:
      function: pattern
      functionOptions:
        match: "^[a-z][a-zA-Z0-9]+$"

  shell-path-kebab-case:
    description: Path segments must use kebab-case or curly-brace parameters
    severity: warn
    given: "$.paths"
    then:
      function: pattern
      functionOptions:
        match: "^(/[a-z0-9{}_/-]+)+$"

  shell-must-have-summary:
    description: All operations must have a summary
    severity: error
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: summary
      function: defined

  shell-must-have-tags:
    description: All operations must have at least one tag
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: tags
      function: defined

  shell-must-have-operation-id:
    description: All operations must have an operationId
    severity: error
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: operationId
      function: defined

  shell-oauth2-security:
    description: Shell APIs use OAuth2 client credentials for authentication
    severity: info
    given: "$.components.securitySchemes[*]"
    then:
      function: schema
      functionOptions:
        schema:
          type: object

  shell-colcocode-required:
    description: B2B Mobility endpoints require colCoCode (Collecting Company Code) parameter
    severity: info
    given: "$.paths[*][get,post].parameters[*]"
    then:
      function: schema
      functionOptions:
        schema:
          type: object

  shell-no-trailing-slash:
    description: Paths must not have trailing slashes
    severity: error
    given: "$.paths"
    then:
      function: pattern
      functionOptions:
        notMatch: ".*/$"

  shell-parameters-have-description:
    description: All parameters should have a description
    severity: info
    given: "$.paths[*][get,post,put,patch,delete].parameters[*]"
    then:
      field: description
      function: defined

  shell-response-200-must-have-content:
    description: 200 responses must have content defined
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete].responses[200]"
    then:
      field: content
      function: defined

  shell-schemas-use-camel-case:
    description: Schema property names should use camelCase
    severity: info
    given: "$.components.schemas[*].properties"
    then:
      function: schema
      functionOptions:
        schema:
          type: object

  shell-pagination-fields:
    description: Paginated list responses should include totalCount, currentPage, pageCount
    severity: info
    given: "$.components.schemas[*ListResponse]"
    then:
      field: properties
      function: defined

  shell-versioned-servers:
    description: Shell API servers must include version in the URL path
    severity: warn
    given: "$.servers[*].url"
    then:
      function: pattern
      functionOptions:
        match: "https://api.shell.com/[a-z-]+/v[0-9]+"