skillhub/docs/api/notification.openapi.yaml

openapi: 3.0.3
info:
  title: SkillHub Notification API
  version: 1.0.0
  description: In-app notification list, unread count, and SSE event contract.
servers:
  - url: /api/web
  - url: /api/v1
paths:
  /notifications:
    get:
      summary: List notifications for the current user
      operationId: listNotifications
      security:
        - sessionAuth: []
      parameters:
        - name: category
          in: query
          required: false
          description: Optional category filter. Profile review notifications reuse REVIEW.
          schema:
            type: string
            enum: [PUBLISH, REVIEW, PROMOTION, REPORT]
          example: REVIEW
        - name: page
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
          example: 0
        - name: size
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
          example: 20
      responses:
        "200":
          description: Notification page.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotificationPageResponse"
        "400":
          description: Invalid category.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Authentication required.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /notifications/unread-count:
    get:
      summary: Get unread notification count for the current user
      operationId: getNotificationUnreadCount
      security:
        - sessionAuth: []
      responses:
        "200":
          description: Unread count.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UnreadCountResponse"
        "401":
          description: Authentication required.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /notifications/sse:
    get:
      summary: Open notification SSE stream for the current user
      operationId: streamNotifications
      security:
        - sessionAuth: []
      responses:
        "200":
          description: SSE stream. Each `notification` event carries NotificationSsePayload.
          content:
            text/event-stream:
              schema:
                type: string
        "401":
          description: Authentication required.
components:
  securitySchemes:
    sessionAuth:
      type: apiKey
      in: cookie
      name: SESSION
  schemas:
    NotificationPageResponse:
      type: object
      properties:
        code:
          type: integer
          example: 0
        msg:
          type: string
          example: ok
        data:
          type: object
          properties:
            items:
              type: array
              items:
                $ref: "#/components/schemas/Notification"
            total:
              type: integer
              format: int64
              example: 1
            page:
              type: integer
              example: 0
            size:
              type: integer
              example: 20
        timestamp:
          type: string
          format: date-time
        requestId:
          type: string
    Notification:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 1001
        category:
          type: string
          enum: [PUBLISH, REVIEW, PROMOTION, REPORT]
          example: REVIEW
        eventType:
          type: string
          description: Known values include REVIEW_SUBMITTED, REVIEW_APPROVED, REVIEW_REJECTED, PROFILE_REVIEW_SUBMITTED, PROMOTION_SUBMITTED, PROMOTION_APPROVED, PROMOTION_REJECTED, REPORT_SUBMITTED, REPORT_RESOLVED, SKILL_PUBLISHED, SUBSCRIPTION_NEW_VERSION, and SUBSCRIPTION_VERSION_YANKED.
          example: PROFILE_REVIEW_SUBMITTED
        title:
          type: string
          example: Profile review submitted
        bodyJson:
          type: string
          description: JSON string. For PROFILE_REVIEW_SUBMITTED it contains profileReviewId, submitterId, and fields.
          example: '{"profileReviewId":77,"submitterId":"user-1","fields":["displayName"]}'
        entityType:
          type: string
          example: PROFILE_REVIEW
        entityId:
          type: integer
          format: int64
          example: 77
        status:
          type: string
          enum: [UNREAD, READ]
          example: UNREAD
        createdAt:
          type: string
          format: date-time
        readAt:
          type: string
          format: date-time
          nullable: true
        targetType:
          type: string
          example: PROFILE_REVIEW
        targetId:
          type: integer
          format: int64
          example: 77
        targetRoute:
          type: string
          description: Profile review notifications route to the admin profile review queue.
          example: /dashboard/reviews?type=profile
    NotificationSsePayload:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 1001
        category:
          type: string
          example: REVIEW
        eventType:
          type: string
          example: PROFILE_REVIEW_SUBMITTED
        title:
          type: string
          example: Profile review submitted
        bodyJson:
          type: string
          example: '{"profileReviewId":77,"submitterId":"user-1","fields":["displayName"]}'
        entityType:
          type: string
          example: PROFILE_REVIEW
        entityId:
          type: integer
          format: int64
          example: 77
        createdAt:
          type: string
          format: date-time
    UnreadCountResponse:
      type: object
      properties:
        code:
          type: integer
          example: 0
        msg:
          type: string
          example: ok
        data:
          type: object
          properties:
            count:
              type: integer
              format: int64
              example: 1
        timestamp:
          type: string
          format: date-time
        requestId:
          type: string
    ErrorResponse:
      type: object
      properties:
        code:
          type: integer
          example: 400
        msg:
          type: string
          example: Invalid category
        timestamp:
          type: string
          format: date-time
        requestId:
          type: string