openapi: 3.0.0
info:
  title: Products API
  version: 1.0.0
  description: API for managing product inventory. This API allows for the creation, retrieval, update, and deletion of product records.
servers:
  - url: https://api.example.com/products/v1
    description: Production server for the Products API.
paths:
  /products:
    get:
      summary: Get all products
      operationId: getAllProducts
      responses:
        '200':
          description: A list of products successfully retrieved.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Product'
    post:
      summary: Add a new product
      operationId: addProduct
      requestBody:
        required: true
        description: Product data to be added.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductInput'
      responses:
        '201':
          description: Product successfully created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
        '400':
          description: Invalid input provided for product creation.
  /products/{productId}:
    get:
      summary: Get a product by ID
      operationId: getProductById
      parameters:
        - name: productId
          in: path
          required: true
          description: Unique identifier of the product to retrieve.
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Product details successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
        '404':
          description: Product not found with the given ID.
    put:
      summary: Update an existing product
      operationId: updateProduct
      parameters:
        - name: productId
          in: path
          required: true
          description: Unique identifier of the product to update.
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        description: Updated product data.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductInput'
      responses:
        '200':
          description: Product successfully updated.
        '400':
          description: Invalid input provided for product update.
        '404':
          description: Product not found with the given ID.
    delete:
      summary: Delete a product
      operationId: deleteProduct
      parameters:
        - name: productId
          in: path
          required: true
          description: Unique identifier of the product to delete.
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: Product successfully deleted. No content.
        '404':
          description: Product not found with the given ID.
components:
  schemas:
    Product:
      type: object
      required:
        - id
        - name
        - price
      properties:
        id:
          type: string
          format: uuid
          description: Unique product identifier.
        name:
          type: string
          description: Name of the product.
        description:
          type: string
          nullable: true
          description: Detailed description of the product.
        price:
          type: number
          format: float
          description: Price of the product.
        stock:
          type: integer
          format: int32
          description: Current stock quantity.
          default: 0
    ProductInput:
      type: object
      required:
        - name
        - price
      properties:
        name:
          type: string
          description: Name of the product.
        description:
          type: string
          nullable: true
          description: Detailed description of the product.
        price:
          type: number
          format: float
          description: Price of the product.
        stock:
          type: integer
          format: int32
          description: Initial stock quantity.
          default: 0