{
  "openapi": "3.0.2",
  "info": {
    "title": "Library Book Management API",
    "version": "1.0.0",
    "description": "A RESTful API for managing books in a library"
  },
  "servers": [
    {
      "url": "http://localhost:3000",
      "description": "Local development server"
    }
  ],
  "components": {
    "schemas": {
      "Book": {
        "type": "object",
        "required": ["isbn", "title", "authors"],
        "properties": {
          "isbn": {
            "type": "string",
            "pattern": "^(?:ISBN(?:-13)?:? )?(?=[0-9]{13}$|(?=(?:[0-9]+[- ]){4})[- 0-9]{17}$)[\\d-]+$",
            "description": "ISBN-13 identifier for the book",
            "example": "978-3-16-148410-0"
          },
          "title": {
            "type": "string",
            "description": "Title of the book",
            "example": "Example Book Title"
          },
          "authors": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "List of authors",
            "example": ["John Doe", "Jane Smith"]
          },
          "publicationYear": {
            "type": "integer",
            "description": "Year of publication",
            "example": 2023
          },
          "genres": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Genres or categories",
            "example": ["Fiction", "Science Fiction"]
          },
          "pageCount": {
            "type": "integer",
            "description": "Total number of pages",
            "example": 350
          },
          "averageRating": {
            "type": "number",
            "format": "float",
            "minimum": 0,
            "maximum": 10,
            "description": "Average rating from 0 to 10",
            "example": 4.5
          },
          "numberOfRatings": {
            "type": "integer",
            "description": "Total number of ratings",
            "example": 1250
          }
        }
      },
      "PartialBook": {
        "type": "object",
        "properties": {
          "isbn": {
            "type": "string",
            "pattern": "^(?:ISBN(?:-13)?:? )?(?=[0-9]{13}$|(?=(?:[0-9]+[- ]){4})[- 0-9]{17}$)[\\d-]+$",
            "description": "ISBN-13 identifier for the book"
          },
          "title": {
            "type": "string",
            "description": "Title of the book"
          },
          "authors": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "List of authors"
          },
          "publicationYear": {
            "type": "integer",
            "description": "Year of publication"
          },
          "genres": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Genres or categories"
          },
          "pageCount": {
            "type": "integer",
            "description": "Total number of pages"
          },
          "averageRating": {
            "type": "number",
            "format": "float",
            "minimum": 0,
            "maximum": 10,
            "description": "Average rating from 0 to 10"
          },
          "numberOfRatings": {
            "type": "integer",
            "description": "Total number of ratings"
          }
        }
      },
      "BadDataIssues": {
        "type": "object",
        "properties": {
          "missingKeys": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Required fields that are missing"
          },
          "extraKeys": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Fields that are not allowed"
          },
          "badValues": {
            "type": "array",
            "items": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "minItems": 2,
              "maxItems": 2
            },
            "description": "Fields with invalid values and their expected types"
          }
        }
      },
      "AuthRequest": {
        "type": "object",
        "required": ["username", "password"],
        "properties": {
          "username": {
            "type": "string",
            "description": "User email or username",
            "example": "user@example.com"
          },
          "password": {
            "type": "string",
            "description": "User password",
            "example": "password123"
          }
        }
      },
      "APIKeyResponse": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string",
            "description": "API key for authentication",
            "example": "abc123def456ghi789"
          }
        }
      },
      "BookErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "description": "Error message with error type prefix",
            "example": "BookError: Book 9783161484100 not found"
          },
          "missingKeys": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Required fields that are missing (only for BadData errors)"
          },
          "extraKeys": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Fields that are not allowed (only for BadData errors)"
          },
          "badValues": {
            "type": "array",
            "items": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "minItems": 2,
              "maxItems": 2
            },
            "description": "Fields with invalid values (only for BadData errors)"
          }
        }
      },
      "InternalServerError": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "example": "Internal Server Error"
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "API key obtained from the /auth endpoint"
      }
    },
    "parameters": {
      "ISBNPathParam": {
        "name": "isbn",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "pattern": "^(?:ISBN(?:-13)?:? )?(?=[0-9]{13}$|(?=(?:[0-9]+[- ]){4})[- 0-9]{17}$)[\\d-]+$"
        },
        "description": "ISBN-13 identifier for the book"
      }
    }
  },
  "paths": {
    "/auth": {
      "post": {
        "summary": "Authenticate user and obtain API key",
        "operationId": "authenticateUser",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AuthRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Authentication successful",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/APIKeyResponse"
                }
              }
            }
          },
          "401": {
            "description": "Invalid credentials",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "example": "BookError: Invalid username or password"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerError"
                }
              }
            }
          }
        }
      }
    },
    "/": {
      "get": {
        "summary": "Get all books",
        "operationId": "getAllBooks",
        "responses": {
          "200": {
            "description": "List of all books",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Book"
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerError"
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Create a new book",
        "operationId": "createBook",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Book"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Book created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Book"
                }
              }
            }
          },
          "400": {
            "description": "Invalid book data or missing required fields",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BookErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing API key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "example": "Unauthorized"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Book with the provided ISBN already exists",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "example": "BookError: Book with id 9783161484100 already exists"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerError"
                }
              }
            }
          }
        }
      }
    },
    "/find": {
      "get": {
        "summary": "Filter books by query parameters",
        "operationId": "filterBooks",
        "parameters": [
          {
            "name": "publishedBefore",
            "in": "query",
            "schema": {
              "type": "integer",
              "description": "Filter books published before this year (inclusive)"
            }
          },
          {
            "name": "publishedAfter",
            "in": "query",
            "schema": {
              "type": "integer",
              "description": "Filter books published after this year (inclusive)"
            }
          },
          {
            "name": "publicationYear",
            "in": "query",
            "schema": {
              "type": "integer",
              "description": "Filter books published in this specific year"
            }
          },
          {
            "name": "title",
            "in": "query",
            "schema": {
              "type": "string",
              "description": "Search for books with titles matching this regex (case-insensitive)"
            }
          },
          {
            "name": "authors",
            "in": "query",
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "Filter books where at least one author matches (case-insensitive)"
            },
            "style": "form",
            "explode": true
          },
          {
            "name": "genres",
            "in": "query",
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "Filter books where at least one genre matches (case-insensitive)"
            },
            "style": "form",
            "explode": true
          },
          {
            "name": "isbn",
            "in": "query",
            "schema": {
              "type": "string",
              "pattern": "^(?:ISBN(?:-13)?:? )?(?=[0-9]{13}$|(?=(?:[0-9]+[- ]){4})[- 0-9]{17}$)[\\d-]+$",
              "description": "Search for books with ISBNs matching this pattern (case-insensitive)"
            }
          },
          {
            "name": "pageCount",
            "in": "query",
            "schema": {
              "type": "integer",
              "description": "Filter books with page count greater than or equal to this value"
            }
          },
          {
            "name": "averageRating",
            "in": "query",
            "schema": {
              "type": "number",
              "format": "float",
              "description": "Filter books with average rating greater than or equal to this value (0-10)"
            }
          },
          {
            "name": "numberOfRatings",
            "in": "query",
            "schema": {
              "type": "integer",
              "description": "Filter books with number of ratings greater than or equal to this value"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Filtered list of books",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Book"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameter",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BookErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerError"
                }
              }
            }
          }
        }
      }
    },
    "/{isbn}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ISBNPathParam"
        }
      ],
      "get": {
        "summary": "Get a book by ISBN",
        "operationId": "getBookByISBN",
        "responses": {
          "200": {
            "description": "Book found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Book"
                }
              }
            }
          },
          "400": {
            "description": "Invalid ISBN format",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "example": "BookError: Invalid book id (9783161484100) [must be ISBN-13 formatted]"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Book not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "example": "BookError: Book 9783161484100 not found"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "patch": {
        "summary": "Update a book",
        "operationId": "updateBook",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PartialBook"
              }
            }
          }
        },
        "responses": {
          "204": {
            "description": "Book updated successfully (no content)"
          },
          "400": {
            "description": "Invalid book data or ISBN format",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BookErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing API key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "example": "Unauthorized"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Book not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "example": "BookError: Book 9783161484100 not found"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerError"
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Delete a book",
        "operationId": "deleteBook",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "204": {
            "description": "Book deleted successfully (no content)"
          },
          "401": {
            "description": "Unauthorized - invalid or missing API key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "example": "Unauthorized"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Book not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "example": "BookError: Book 9783161484100 not found"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerError"
                }
              }
            }
          }
        }
      }
    }
  },
  "security": []
}