# yaml-language-server: $schema=https://raw.githubusercontent.com/OAI/OpenAPI-Specification/refs/heads/main/_archive_/schemas/v3.0/schema.yaml
openapi: 3.0.0
info:
  title: Example App Backend API
  version: "1.0.0"
  description: API for the Example App backend service.
servers:
  - url: http://localhost:8080
    description: Local development server
components:
  securitySchemes:
    cookieAuth:
      type: apiKey
      in: cookie
      name: auth
      description: Cookie-based authentication
  schemas:
    Error:
      type: object
      properties:
        type:
          type: string
          description: Categorization of the error for programmatic handling.
          enum:
            - AUTHENTICATION_ERROR
            - AUTHORIZATION_ERROR
            - VALIDATION_ERROR
            - BAD_REQUEST_ERROR
            - NOT_FOUND_ERROR
            - SERVER_ERROR
            - UNKNOWN_ERROR
          example: AUTHENTICATION_ERROR
        key:
          description: A unique error code or identifier for specific error cases.
          type: string
          maxLength: 200
          example: example key
        message:
          type: string
          description: A human-readable message explaining the error.
          maxLength: 200
          example: example message
        details:
          type: object
          description: Additional context or metadata regarding the error (e.g.,
            specific field validation failures).
          x-go-type-skip-optional-pointer: true
          x-go-type: any
          additionalProperties: true
          example: {}
      required:
        - type
        - key
        - message
      description: Schema representing Error.
      example: {}
    UUID:
      type: string
      format: uuid
      x-go-type: uuid.UUID
      x-go-type-import:
        path: github.com/google/uuid
        name: uuid
      description: Schema representing UUID.
      example: example
    User:
      type: object
      properties:
        id:
          description: Id of the user.
          allOf:
            - $ref: "#/components/schemas/UUID"
        name:
          type: string
          description: Full name or display name of the user.
          example: "Example User"
      required:
        - id
        - name
      description: Schema representing User.
      example: {}
    Claims:
      type: object
      properties:
        iss:
          type: string
          description: The issuer of the token.
          example: "example-app-backend"
        sub:
          description: The subject of the token (User ID).
          allOf:
            - $ref: "#/components/schemas/UUID"
        iat:
          type: integer
          format: int64
          description: Issued At timestamp (Unix epoch).
          example: 1
        exp:
          type: integer
          format: int64
          description: Expiration timestamp (Unix epoch).
          example: 1
      required:
        - iss
        - sub
        - iat
        - exp

      description: Schema representing Claims.
      example: {}
    Scan:
      type: object
      properties:
        isbn:
          type: string
          x-go-name: ISBN
          description: The International Standard Book Number.
          example: 978-3-16-148410-0
      required:
        - isbn

      description: Schema representing Scan.
      example: {}
    Book:
      type: object
      properties:
        id:
          type: integer
          description: User facing id of the book.
          example: 1
        title:
          type: string
          minLength: 1
          maxLength: 200
          description: The title of the book.
          example: example title
        authors:
          type: string
          minLength: 1
          maxLength: 500
          description: A comma-separated list or string of book authors.
          example: example authors
        description:
          type: string
          minLength: 0
          maxLength: 2048
          description: A brief summary or synopsis of the book.
          example: example description
        lentBy:
          description: The user who has lent the book from the library.
            Undefined if the boook is not lent.
          allOf:
            - $ref: "#/components/schemas/User"
        coverUrl:
          type: string
          format: url
          description: Link to the book's cover image.
          example: example cover_url
      required:
        - id
        - title
        - authors

      description: Schema representing Book.
      example: {}
    BookDetails:
      allOf:
        - $ref: "#/components/schemas/Book"
        - type: object
          properties:
            isbn:
              type: string
              x-go-name: ISBN
              minLength: 9
              maxLength: 20
              description: The ISBN of the book.
              example: example isbn
            publisher:
              type: string
              minLength: 1
              maxLength: 200
              description: The entity that published the book.
              example: example publisher
            publishedAt:
              type: integer
              multipleOf: 1
              minimum: 0
              description: The publication year or timestamp.
              example: 1
            owner:
              description: The user who owns the bool. Undefined if the boook is
                public.
              allOf:
                - $ref: "#/components/schemas/User"
          required:
            - isbn
            - publisher
            - publishedAt
          example: {}
      description: Schema representing BookDetails.
    BookRequest:
      type: object
      properties:
        title:
          type: string
          minLength: 1
          maxLength: 200
          description: "The title of the book. (ctx: schema.BookRequest.properties.title)"
          example: example title
        authors:
          type: string
          minLength: 1
          maxLength: 500
          description: "A comma-separated list or string of book authors. (ctx: schema.BookRequest.properties.authors)"
          example: example authors
        isbn:
          type: string
          x-go-name: ISBN
          minLength: 9
          maxLength: 20
          description: "The ISBN of the book. (ctx: schema.BookRequest.properties.isbn)"
          example: example isbn
        description:
          type: string
          minLength: 0
          maxLength: 2048
          description: "A brief summary or synopsis of the book. (ctx: schema.BookRequest.properties.description)"
          example: example description
        publisher:
          type: string
          minLength: 1
          maxLength: 200
          description: "The entity that published the book. (ctx: schema.BookRequest.properties.publisher)"
          example: example publisher
        publishedAt:
          type: integer
          multipleOf: 1
          minimum: 0
          description: "The publication year or timestamp. (ctx: schema.BookRequest.properties.publishedAt)"
          example: 1
        public:
          type: boolean
          description: Whether the book is publicly owened or owned by the
            creating user.

          example: true
        coverUrl:
          type: string
          format: url
          minLength: 0
          maxLength: 1024
          description: "Link to the book's cover image. (ctx: schema.BookRequest.properties.coverUrl)"
          example: example cover_url
      required:
        - title
        - authors
        - isbn
        - publisher
        - publishedAt
        - public

      description: Schema representing BookRequest.
      example: {}
    Lending:
      type: object
      properties:
        user:
          description: The uuid of the user, who has lent the book
          allOf:
            - $ref: "#/components/schemas/UUID"
        startedAt:
          type: string
          format: date-time
          description: The ID of the user borrowing the book.
          example: example startedAt
        returnedAt:
          type: string
          format: date-time
          description: Timestamp when the book was returned. Undefined if still
            out.
          example: example returnedAt
      required:
        - user
        - startedAt

      description: Schema representing Lending.
      example: {}
  responses:
    Error400:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    Error401:
      description: Unauthorized – missing or invalid auth cookie
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    Error403:
      description: Forbidden – this is probably not your book
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    Error404:
      description: Not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    Error500:
      description: Server error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
security:
  - cookieAuth: []

paths:
  /auth/login:
    post:
      summary: Login a user and receive an authentication cookie
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UUID"
        description: Request body for POST /auth/login
      responses:
        "200":
          description: Successful login, authentication cookie set
          headers:
            Set-Cookie:
              schema:
                type: string
                example: auth=eyJhbGci...; Path=/; HttpOnly
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Claims"
        "400":
          description: Invalid request payload
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/Error500"
      security: []
      tags:
        - Auth
      operationId: post_auth_login
      description: Log in a user and receive an authentication cookie
  /auth/logout:
    post:
      summary: Logout the current user
      responses:
        "204":
          description: Successful logout and the cookie was removed
          headers:
            Set-Cookie:
              description: >
                Sets the auth cookie to an empty value and expires it immediately by
                setting Max-Age to 0. The token gets invalidated.
              schema:
                type: string
                example: auth=; Path=/; HttpOnly; Max-Age=0
        "401":
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/Error500"
      tags:
        - Auth
      operationId: post_auth_logout
      description: Logout the current user
  /auth:
    get:
      summary: Retrieve the claims for the currently authenticated user
      responses:
        "200":
          description: Claims of the authenticated user
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Claims"
        "401":
          $ref: "#/components/responses/Error401"
        "500":
          $ref: "#/components/responses/Error500"
      security: []
      tags:
        - Auth
      operationId: get_auth
      description: Retrieve the claims for the currently authenticated user

  /auth/users:
    get:
      summary: List all users
      responses:
        "200":
          description: Array of user objects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/User"
                example: []
        "500":
          $ref: "#/components/responses/Error500"
      security: []
      tags:
        - Auth
      operationId: get_auth_users
      description: List all users
  /books:
    get:
      summary: Get all books
      responses:
        "200":
          description: Array of books
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Book"
                example: []
        "500":
          $ref: "#/components/responses/Error500"
      security: [] #no security needed

      tags:
        - Books
      operationId: get_books
      description: Get all books
    post:
      summary: Register a new book
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BookRequest"

        description: Request body for POST /books
      responses:
        "200":
          description: The new book
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Book"
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "500":
          $ref: "#/components/responses/Error500"
      tags:
        - Books
      operationId: post_books
      description: Register a new book
  /books/{bookID}:
    parameters:
      - name: bookID
        in: path
        required: true
        schema:
          type: integer
          minimum: 0

        description: Parameter bookID for /books/{bookID}
    get:
      summary: Get the details of a book
      responses:
        "200":
          description: BookDetails
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BookDetails"
        "404":
          $ref: "#/components/responses/Error404"
        "500":
          $ref: "#/components/responses/Error500"
      security: [] #no security needed

      tags:
        - Books
      operationId: get_books_bookID
      description: Get the details of a book
    put:
      summary: Update a book
      description: |
        The field lentBy will be ignored. If you want to lend a book, please use the corresponding route.
        The field owner will only be obeyed if you own the book and set it to null / undefined.

      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BookRequest"

        description: Request body for PUT /books/{bookID}
      responses:
        "200":
          description: The new book
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BookDetails"
        "400":
          $ref: "#/components/responses/Error400"
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "500":
          $ref: "#/components/responses/Error500"
      tags:
        - Books
      operationId: put_books_bookID
    delete:
      summary: Delete a book
      responses:
        "204":
          description: Book deleted successfully
        "403":
          $ref: "#/components/responses/Error403"
        "404":
          $ref: "#/components/responses/Error404"
        "500":
          $ref: "#/components/responses/Error500"
      tags:
        - Books
      operationId: delete_books_bookID
      description: Delete a book
  /books/{bookID}/lending:
    parameters:
      - name: bookID
        in: path
        required: true
        schema:
          type: integer
          minimum: 0
        description: Parameter bookID for /books/{bookID}/lending
    post:
      summary: Lend a book
      responses:
        "204":
          description: The book is successfully lent
        "400":
          description: Bad request - The book is most likely already lent
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Error401"
        "404":
          $ref: "#/components/responses/Error404"
        "500":
          $ref: "#/components/responses/Error500"
      tags:
        - Lending
      operationId: post_books_bookID_lending
      description: Lend a book
    delete:
      summary: End a lending (return a book)
      responses:
        "204":
          description: The lending is successfully ended.
        "401":
          $ref: "#/components/responses/Error401"
        "403":
          description: Forbidden – you do not have an open lending
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          $ref: "#/components/responses/Error404"
        "500":
          $ref: "#/components/responses/Error500"
      tags:
        - Lending
      operationId: delete_books_bookID_lending
      description: End a lending (return a book)
  /lookup:
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Scan"

        description: Request body for POST /lookup
      responses:
        "200":
          description: Looked up book
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BookRequest"
        "401":
          $ref: "#/components/responses/Error401"
        "404":
          $ref: "#/components/responses/Error404"
        "500":
          $ref: "#/components/responses/Error500"
      tags:
        - Lookup
      operationId: post_lookup
      description: POST operation for /lookup