.spectral.yaml

# Source: https://docs.stoplight.io/docs/spectral/4dec24461f3af-open-api-rules
extends:
  - spectral:oas
rules:
  # API 버전 규칙 : v로 시작하고 숫자와 점으로 이루어져야 함
  api-version-convention:
    description: API version should follow the convention
    given: $.info.version
    severity: error
    then:
      function: pattern
      functionOptions:
        match: "^v[0-9\\.]+$"
      message: API version should follow the convention v1, v2.1, v3.0.1, etc.

  # 모든 엔드포인트는 tags를 포함해야 함
  operation-tags-convention:
    description: All Operation should include tags
    given: $.paths[*][*]
    severity: error
    then:
      - field: tags
        function: truthy
        message: Tags are required

  # 모든 엔드포인트는 operationId를 포함해야 함 (.WithName 으로 지정)
  operation-operationid-convention:
    description: All Operation should include operationId
    given: $.paths[*][*]
    severity: error
    then:
      - field: operationId
        function: truthy
        message: OperationId is required
  
  # 모든 엔드포인트는 summary와 description을 포함해야 함
  operation-summary-description-convention:
    description: All Operation should include summary and description
    given: $.paths[*][*]
    severity: error
    then:
      - field: 'summary'
        function: truthy
        message: Summary is required
      - field: 'description'
        function: truthy
        message: Description is required  
  
  # 응답이 정의되어 있어야함
  operation-response-convention:
    description: All Operation should include response
    given: $.paths[*][*]
    severity: error
    then:
      - field: responses
        function: truthy
        message: Responses are required

  # 응답 코드 규칙 : 200, 401, 500 응답 코드가 있어야 함
  operation-responsecode-convention:
    description: All Operation response should include 200, 401, 500
    given: $.paths[*][*].responses
    severity: error
    then:
      - field: '200'
        function: truthy
        message: Response 200 is required
      - field: '401'
        function: truthy
        message: Response 401 is required
      - field: '500'
        function: truthy
        message: Response 500 is required

  # 400, 401, 404를 제외한 모든 응답 코드는 content를 포함해야함
  operation-responsedetail-content-convention:
    description: All Operation response might include content, except 400, 401 and 404
    given: $.paths[*][*].responses[?(@property != '400' && @property != '401' && @property != '404')]
    severity: error
    then:
      - field: 'content'
        function: truthy
        message: Content is required

  # Ensure endpoints with path variables define a 404 response
  # path에 path variable이 있다면 404 응답 코드가 있어야 함
  path-variables-require-404:
    description: Path variables must include a 404 response
    severity: error
    given: $.paths[*][*].parameters[?(@.in == 'path')]^^
    then:
      - field: responses.404
        function: truthy
        message: Response 404 is required

  # Ensure POST, PUT, PATCH methods define a 400 response
  # verb가 POST, PUT, PATCH일 경우 400 응답코드가 있어야 함
  post-put-patch-require-400:
    description: POST, PUT, PATCH methods must include a 400 response
    given: $.paths[*][?(@property == 'post' || @property == 'put' || @property == 'patch')]
    severity: error
    then:
      - field: responses.400
        function: truthy
        message: Response 400 is required