openapi: 3.1.0
info:
    title: WebcamService API
    version: 1.0.0
paths:
    /api/webcam/v1/list-webcams:
        get:
            tags:
                - WebcamService
            summary: ListWebcams
            operationId: ListWebcams
            parameters:
                - name: zoom
                  in: query
                  required: false
                  schema:
                    type: integer
                    format: int32
                - name: bound_w
                  in: query
                  required: false
                  schema:
                    type: number
                    format: double
                - name: bound_s
                  in: query
                  required: false
                  schema:
                    type: number
                    format: double
                - name: bound_e
                  in: query
                  required: false
                  schema:
                    type: number
                    format: double
                - name: bound_n
                  in: query
                  required: false
                  schema:
                    type: number
                    format: double
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ListWebcamsResponse'
                "400":
                    description: Validation error
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ValidationError'
                default:
                    description: Error response
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
    /api/webcam/v1/get-webcam-image:
        get:
            tags:
                - WebcamService
            summary: GetWebcamImage
            operationId: GetWebcamImage
            parameters:
                - name: webcam_id
                  in: query
                  required: false
                  schema:
                    type: string
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/GetWebcamImageResponse'
                "400":
                    description: Validation error
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ValidationError'
                default:
                    description: Error response
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
components:
    schemas:
        Error:
            type: object
            properties:
                message:
                    type: string
                    description: Error message (e.g., 'user not found', 'database connection failed')
            description: Error is returned when a handler encounters an error. It contains a simple error message that the developer can customize.
        FieldViolation:
            type: object
            properties:
                field:
                    type: string
                    description: The field path that failed validation (e.g., 'user.email' for nested fields). For header validation, this will be the header name (e.g., 'X-API-Key')
                description:
                    type: string
                    description: Human-readable description of the validation violation (e.g., 'must be a valid email address', 'required field missing')
            required:
                - field
                - description
            description: FieldViolation describes a single validation error for a specific field.
        ValidationError:
            type: object
            properties:
                violations:
                    type: array
                    items:
                        $ref: '#/components/schemas/FieldViolation'
                    description: List of validation violations
            required:
                - violations
            description: ValidationError is returned when request validation fails. It contains a list of field violations describing what went wrong.
        ListWebcamsRequest:
            type: object
            properties:
                zoom:
                    type: integer
                    format: int32
                boundW:
                    type: number
                    format: double
                boundS:
                    type: number
                    format: double
                boundE:
                    type: number
                    format: double
                boundN:
                    type: number
                    format: double
        ListWebcamsResponse:
            type: object
            properties:
                webcams:
                    type: array
                    items:
                        $ref: '#/components/schemas/WebcamEntry'
                clusters:
                    type: array
                    items:
                        $ref: '#/components/schemas/WebcamCluster'
                totalInView:
                    type: integer
                    format: int32
        WebcamEntry:
            type: object
            properties:
                webcamId:
                    type: string
                title:
                    type: string
                lat:
                    type: number
                    format: double
                lng:
                    type: number
                    format: double
                category:
                    type: string
                country:
                    type: string
        WebcamCluster:
            type: object
            properties:
                lat:
                    type: number
                    format: double
                lng:
                    type: number
                    format: double
                count:
                    type: integer
                    format: int32
                categories:
                    type: array
                    items:
                        type: string
        GetWebcamImageRequest:
            type: object
            properties:
                webcamId:
                    type: string
        GetWebcamImageResponse:
            type: object
            properties:
                thumbnailUrl:
                    type: string
                playerUrl:
                    type: string
                title:
                    type: string
                windyUrl:
                    type: string
                lastUpdated:
                    type: string
                    format: int64
                error:
                    type: string