openapi: 3.1.0
info:
  title: GoLinks API
  description: API documentation for GoLinks service
  version: 1.0.0

servers:
  - url: http://localhost:8000
    description: Local development server

paths:
  /api/pages:
    get:
      summary: List all pages
      description: Retrieve a paginated list of all pages
      parameters:
        - in: query
          name: page
          schema:
            type: integer
          description: Page number for pagination
        - in: query
          name: page_size
          schema:
            type: integer
          description: Number of items per page
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageList'

    post:
      summary: Create a new page
      description: Create a new page with the provided data
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PageCreate'
      responses:
        '201':
          description: Page created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page'

  /api/posts:
    get:
      summary: List all posts
      description: Retrieve a paginated list of all posts
      parameters:
        - in: query
          name: page
          schema:
            type: integer
          description: Page number for pagination
        - in: query
          name: page_size
          schema:
            type: integer
          description: Number of items per page
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostList'

    post:
      summary: Create a new post
      description: Create a new post with the provided data
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostCreate'
      responses:
        '201':
          description: Post created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Post'

  /api/collections:
    get:
      summary: List all collections
      description: Retrieve a paginated list of all image collections
      parameters:
        - in: query
          name: page
          schema:
            type: integer
          description: Page number for pagination
        - in: query
          name: page_size
          schema:
            type: integer
          description: Number of items per page
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionList'

    post:
      summary: Create a new collection
      description: Create a new image collection
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CollectionCreate'
      responses:
        '201':
          description: Collection created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionResponse'

  /api/collections/{collection_id}:
    delete:
      summary: Delete a collection
      description: Delete a collection and all its images
      parameters:
        - in: path
          name: collection_id
          required: true
          schema:
            type: string
            format: uuid
          description: The ID of the collection to delete
      responses:
        '200':
          description: Collection deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

  /api/collections/{collection_id}/upload_images:
    post:
      summary: Upload images to a collection
      description: Upload one or more images to a collection with optional descriptions
      parameters:
        - in: path
          name: collection_id
          required: true
          schema:
            type: string
            format: uuid
          description: The ID of the collection to upload images to
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: array
                  items:
                    type: string
                    format: binary
                  description: List of image files to upload. Only image/* content types are allowed.
                descriptions:
                  type: array
                  items:
                    type: string
                  description: Optional list of descriptions for the uploaded images. Each description corresponds to the image at the same index.
              required:
                - file
      responses:
        '201':
          description: Images uploaded successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum: [success]
                    example: success
                  message:
                    type: string
                    example: "Successfully uploaded 2 images"
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Image'

  /api/images/{image_id}:
    delete:
      summary: Delete an image
      description: Delete a specific image from a collection
      parameters:
        - in: path
          name: image_id
          required: true
          schema:
            type: string
            format: uuid
          description: The ID of the image to delete
      responses:
        '200':
          description: Image deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

components:
  schemas:
    Page:
      type: object
      properties:
        id:
          type: integer
        url:
          type: string
        title:
          type: string
        summary:
          type: string
        content:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    PageCreate:
      type: object
      required:
        - url
        - title
      properties:
        url:
          type: string
        title:
          type: string
        summary:
          type: string
        content:
          type: string

    PageList:
      type: object
      properties:
        count:
          type: integer
        next:
          type: string
          nullable: true
        previous:
          type: string
          nullable: true
        results:
          type: array
          items:
            $ref: '#/components/schemas/Page'

    Post:
      type: object
      properties:
        id:
          type: integer
        title:
          type: string
        content:
          type: string
        tag_details:
          type: array
          items:
            $ref: '#/components/schemas/Tag'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    PostCreate:
      type: object
      required:
        - title
        - content
      properties:
        title:
          type: string
        content:
          type: string
        tags:
          type: array
          items:
            type: string
          description: List of tag slugs to associate with the post

    PostList:
      type: object
      properties:
        count:
          type: integer
        next:
          type: string
          nullable: true
        previous:
          type: string
          nullable: true
        results:
          type: array
          items:
            $ref: '#/components/schemas/Post'

    Tag:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        slug:
          type: string
        description:
          type: string

    Collection:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        description:
          type: string
        image_count:
          type: integer
        created_at:
          type: string
          format: date-time

    CollectionCreate:
      type: object
      required:
        - name
      properties:
        name:
          type: string
        description:
          type: string

    CollectionList:
      type: object
      properties:
        count:
          type: integer
        next:
          type: string
          nullable: true
        previous:
          type: string
          nullable: true
        results:
          type: array
          items:
            $ref: '#/components/schemas/Collection'

    CollectionResponse:
      type: object
      properties:
        status:
          type: string
          enum: [success]
        message:
          type: string
        data:
          $ref: '#/components/schemas/Collection'

    Image:
      type: object
      properties:
        id:
          type: string
          format: uuid
        collection:
          type: string
          format: uuid
        title:
          type: string
        description:
          type: string
        content_type:
          type: string
        size:
          type: integer
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        url:
          type: string

    SuccessResponse:
      type: object
      properties:
        status:
          type: string
          enum: [success]
        message:
          type: string