CodeProject API Rules

extends:
  - spectral:oas

# Spectral linting rules for CodeProject APIs.
# Covers both the public REST API at api.codeproject.com (OAuth 2.0 protected,
# read-mostly resources) and the locally hosted CodeProject.AI Server REST API
# (no auth by default, multipart uploads, /v1/* paths).
rules:
  codeproject-info-contact:
    description: API contact information must be present.
    severity: error
    given: "$.info"
    then:
      field: contact
      function: truthy

  codeproject-public-server-https:
    description: Public CodeProject API servers must use HTTPS.
    severity: error
    given: "$.servers[?(@.url && @.url.indexOf('codeproject.com') > -1)].url"
    then:
      function: pattern
      functionOptions:
        match: "^https://"

  codeproject-ai-server-localhost:
    description: CodeProject.AI Server example server URL should reference localhost.
    severity: info
    given: "$.servers[?(@.url && @.url.indexOf('localhost') > -1)].url"
    then:
      function: pattern
      functionOptions:
        match: "localhost"

  codeproject-operation-id:
    description: Every operation must declare a unique operationId.
    severity: error
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: operationId
      function: truthy

  codeproject-operation-tags:
    description: Operations must declare at least one tag.
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: tags
      function: schema
      functionOptions:
        schema:
          type: array
          minItems: 1

  codeproject-version-prefix:
    description: All paths must be versioned under /v1/.
    severity: warn
    given: "$.paths"
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          patternProperties:
            "^/v1/": {}

  codeproject-oauth2-on-my:
    description: My/* operations must require oauth2 with at least one scope.
    severity: error
    given: "$.paths['/v1/My/Profile','/v1/My/Reputation','/v1/My/Articles','/v1/My/Answers','/v1/My/Blog','/v1/My/Bookmarks','/v1/My/Notifications','/v1/My/Tips'][get].security"
    then:
      function: schema
      functionOptions:
        schema:
          type: array
          minItems: 1

  codeproject-error-responses:
    description: Operations should declare 4xx error responses.
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete].responses"
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          anyOf:
            - required: ["400"]
            - required: ["401"]
            - required: ["403"]
            - required: ["404"]

  codeproject-ai-multipart:
    description: CodeProject.AI Server upload endpoints should accept multipart/form-data.
    severity: info
    given: "$.paths[?(@property && @property.indexOf('/v1/vision/') > -1)].post.requestBody.content"
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          required: ["multipart/form-data"]