openapi.yml

openapi: 3.0.3
info:
  title: Library API
  description: A RESTful API for managing a library system with books, members, and checkouts
  version: 1.0.0
servers:
  - url: http://localhost:3000/api
    description: Development server

paths:
  /:
    get:
      summary: Get API information
      description: Returns information about the API including version and available endpoints
      tags:
        - Root
      responses:
        '200':
          description: API information retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Library API
                  version:
                    type: string
                    example: 1.0.0
                  endpoints:
                    type: object

  /books:
    get:
      summary: Get all books
      description: Retrieve a list of all books in the library
      tags:
        - Books
      responses:
        '200':
          description: List of books retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  books:
                    type: array
                    items:
                      $ref: '#/components/schemas/Book'
                  total:
                    type: integer
                    example: 10

    post:
      summary: Create a new book
      description: Add a new book to the library
      tags:
        - Books
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - title
                - author
                - isbn
              properties:
                title:
                  type: string
                  example: The Great Gatsby
                author:
                  type: string
                  example: F. Scott Fitzgerald
                isbn:
                  type: string
                  example: 978-0-7432-7356-5
                publishedYear:
                  type: integer
                  example: 1925
                genre:
                  type: string
                  example: Classic Fiction
      responses:
        '201':
          description: Book created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Book created successfully
                  book:
                    $ref: '#/components/schemas/Book'

  /books/{id}:
    get:
      summary: Get book by ID
      description: Retrieve a specific book by its ID
      tags:
        - Books
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
          description: Book ID
      responses:
        '200':
          description: Book retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Book'
        '404':
          description: Book not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    put:
      summary: Update a book
      description: Update an existing book's information
      tags:
        - Books
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
          description: Book ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                author:
                  type: string
                isbn:
                  type: string
                publishedYear:
                  type: integer
                genre:
                  type: string
                available:
                  type: boolean
      responses:
        '200':
          description: Book updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Book updated successfully
                  book:
                    $ref: '#/components/schemas/Book'
        '404':
          description: Book not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    delete:
      summary: Delete a book
      description: Remove a book from the library
      tags:
        - Books
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
          description: Book ID
      responses:
        '200':
          description: Book deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Book deleted successfully
        '404':
          description: Book not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /members:
    get:
      summary: Get all members
      description: Retrieve a list of all library members
      tags:
        - Members
      responses:
        '200':
          description: List of members retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  members:
                    type: array
                    items:
                      $ref: '#/components/schemas/Member'
                  total:
                    type: integer
                    example: 5

    post:
      summary: Create a new member
      description: Register a new library member
      tags:
        - Members
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - email
              properties:
                name:
                  type: string
                  example: Alice Johnson
                email:
                  type: string
                  format: email
                  example: alice.johnson@email.com
                membershipType:
                  type: string
                  enum: [Basic, Standard, Premium]
                  example: Premium
      responses:
        '201':
          description: Member created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Member created successfully
                  member:
                    $ref: '#/components/schemas/Member'

  /members/{id}:
    get:
      summary: Get member by ID
      description: Retrieve a specific member by their ID
      tags:
        - Members
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
          description: Member ID
      responses:
        '200':
          description: Member retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Member'
        '404':
          description: Member not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    put:
      summary: Update a member
      description: Update an existing member's information
      tags:
        - Members
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
          description: Member ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                email:
                  type: string
                  format: email
                membershipType:
                  type: string
                  enum: [Basic, Standard, Premium]
      responses:
        '200':
          description: Member updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Member updated successfully
                  member:
                    $ref: '#/components/schemas/Member'
        '404':
          description: Member not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    delete:
      summary: Delete a member
      description: Remove a member from the library system
      tags:
        - Members
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
          description: Member ID
      responses:
        '200':
          description: Member deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Member deleted successfully
        '404':
          description: Member not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /checkouts:
    get:
      summary: Get all checkouts
      description: Retrieve a list of all checked out books with associated member details
      tags:
        - Checkouts
      responses:
        '200':
          description: List of checkouts retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  checkouts:
                    type: array
                    items:
                      $ref: '#/components/schemas/Checkout'
                  total:
                    type: integer
                    example: 3

components:
  schemas:
    Book:
      type: object
      properties:
        id:
          type: integer
          example: 1
        title:
          type: string
          example: The Great Gatsby
        author:
          type: string
          example: F. Scott Fitzgerald
        isbn:
          type: string
          example: 978-0-7432-7356-5
        publishedYear:
          type: integer
          example: 1925
        genre:
          type: string
          example: Classic Fiction
        available:
          type: boolean
          example: true

    Member:
      type: object
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          example: Alice Johnson
        email:
          type: string
          format: email
          example: alice.johnson@email.com
        membershipDate:
          type: string
          format: date
          example: '2024-01-15'
        membershipType:
          type: string
          enum: [Basic, Standard, Premium]
          example: Premium

    Checkout:
      type: object
      properties:
        book:
          type: object
          properties:
            id:
              type: integer
              example: 3
            title:
              type: string
              example: '1984'
            author:
              type: string
              example: George Orwell
            isbn:
              type: string
              example: 978-0-452-28423-4
        member:
          type: object
          properties:
            id:
              type: integer
              example: 2
            name:
              type: string
              example: Bob Martinez
            email:
              type: string
              format: email
              example: bob.martinez@email.com
        checkoutDate:
          type: string
          format: date
          example: '2024-12-15'

    Error:
      type: object
      properties:
        error:
          type: string
          example: Resource not found

tags:
  - name: Root
    description: API information
  - name: Books
    description: Book management operations
  - name: Members
    description: Member management operations
  - name: Checkouts
    description: Checkout tracking operations