openapi.yaml

openapi: 3.0.3
info:
  title: Typescript REST API
  version: 1.0.0
  description: |
    API for managing marketplace users, categories, and products.
    It includes JWT authentication, role-based authorization, soft deletion,
    pagination, and collection-based search.

    Field and parameter names preserve the application's current contract.
    For this reason, users and categories use `limite`/`desde`, while products
    use `limit`/`from`.
servers:
  - url: http://localhost:3000/api
    description: Local server

tags:
  - name: Authentication
    description: User sign-in and JWT issuance.
  - name: Users
    description: User management.
  - name: Categories
    description: Category management.
  - name: Products
    description: Product management.
  - name: Search
    description: Search across users, categories, and products.

paths:
  /auth/login:
    post:
      tags: [Authentication]
      summary: Sign in
      description: Validates the email and password of an active user and returns a JWT.
      operationId: login
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
      responses:
        '200':
          description: Authentication successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginResponse'
        '400':
          $ref: '#/components/responses/BadRequest'

  /usuarios:
    get:
      tags: [Users]
      summary: List active users
      operationId: listUsers
      parameters:
        - $ref: '#/components/parameters/Limite'
        - $ref: '#/components/parameters/Desde'
      responses:
        '200':
          description: Paginated list of active users.
          content:
            application/json:
              schema:
                type: object
                required: [total, usuarios]
                properties:
                  total:
                    type: integer
                    example: 12
                  usuarios:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
    post:
      tags: [Users]
      summary: Create a user
      operationId: createUser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
      responses:
        '201':
          description: User created.
          content:
            application/json:
              schema:
                type: object
                required: [msg, usuario]
                properties:
                  msg:
                    type: string
                    example: User created successfully
                  usuario:
                    $ref: '#/components/schemas/User'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalError'

  /usuarios/{id}:
    put:
      tags: [Users]
      summary: Update a user
      description: Requires authentication and only allows a user to update their own profile. Role and account-status changes are ignored. If `password` is included, it is stored as a hash.
      operationId: updateUser
      security:
        - tokenJWT: []
      parameters:
        - $ref: '#/components/parameters/Id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUserRequest'
      responses:
        '200':
          description: User updated.
          content:
            application/json:
              schema:
                type: object
                required: [msg, usuario]
                properties:
                  msg:
                    type: string
                    example: User updated successfully
                  usuario:
                    $ref: '#/components/schemas/User'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
    delete:
      tags: [Users]
      summary: Soft-delete a user
      description: Requires an authenticated user with the `admin_rol` or `ventas_rol` role.
      operationId: deleteUser
      security:
        - tokenJWT: []
      parameters:
        - $ref: '#/components/parameters/Id'
      responses:
        '200':
          description: User deactivated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  usuario:
                    $ref: '#/components/schemas/User'
                  usuarioAutenticado:
                    $ref: '#/components/schemas/User'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /categorias:
    get:
      tags: [Categories]
      summary: List active categories
      operationId: listCategories
      parameters:
        - $ref: '#/components/parameters/Limite'
        - $ref: '#/components/parameters/Desde'
      responses:
        '200':
          description: Paginated list of active categories with the creator user expanded.
          content:
            application/json:
              schema:
                type: object
                required: [total, categorias]
                properties:
                  total:
                    type: integer
                    example: 4
                  categorias:
                    type: array
                    items:
                      $ref: '#/components/schemas/ExpandedCategory'
    post:
      tags: [Categories]
      summary: Create a category
      description: Requires authentication. The name is converted to uppercase and the creator is obtained from the token.
      operationId: createCategory
      security:
        - tokenJWT: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CategoryRequest'
      responses:
        '201':
          description: Category created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Category'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /categorias/{id}:
    get:
      tags: [Categories]
      summary: Get a category
      operationId: getCategory
      parameters:
        - $ref: '#/components/parameters/Id'
      responses:
        '200':
          description: Category found with the creator user expanded.
          content:
            application/json:
              schema:
                type: object
                required: [categoria]
                properties:
                  categoria:
                    $ref: '#/components/schemas/ExpandedCategory'
        '400':
          $ref: '#/components/responses/BadRequest'
    put:
      tags: [Categories]
      summary: Update a category
      description: Requires authentication. Only the category owner can update it. The name is converted to uppercase and the user is obtained from the token.
      operationId: updateCategory
      security:
        - tokenJWT: []
      parameters:
        - $ref: '#/components/parameters/Id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CategoryRequest'
      responses:
        '200':
          description: Category updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Category'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    delete:
      tags: [Categories]
      summary: Soft-delete a category
      description: Requires authentication and the `admin_rol` role.
      operationId: deleteCategory
      security:
        - tokenJWT: []
      parameters:
        - $ref: '#/components/parameters/Id'
      responses:
        '200':
          description: Category deactivated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  categoria:
                    $ref: '#/components/schemas/Category'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /productos:
    get:
      tags: [Products]
      summary: List active products
      operationId: listProducts
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/From'
      responses:
        '200':
          description: Paginated list of active products with user and category expanded.
          content:
            application/json:
              schema:
                type: object
                required: [total, products]
                properties:
                  total:
                    type: integer
                    example: 25
                  products:
                    type: array
                    items:
                      $ref: '#/components/schemas/ExpandedProduct'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      tags: [Products]
      summary: Create a product
      description: Requires authentication. The name is stored in uppercase and the owner is always obtained from the token.
      operationId: createProduct
      security:
        - tokenJWT: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProductRequest'
      responses:
        '201':
          description: Product created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /productos/{id}:
    get:
      tags: [Products]
      summary: Get a product
      operationId: getProduct
      parameters:
        - $ref: '#/components/parameters/Id'
      responses:
        '200':
          description: Product found with user and category expanded.
          content:
            application/json:
              schema:
                type: object
                required: [product]
                properties:
                  product:
                    $ref: '#/components/schemas/ExpandedProduct'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
    put:
      tags: [Products]
      summary: Update a product
      description: Requires authentication. Only the product owner can update it; `nombre` is required and converted to uppercase.
      operationId: updateProduct
      security:
        - tokenJWT: []
      parameters:
        - $ref: '#/components/parameters/Id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateProductRequest'
      responses:
        '200':
          description: Product updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      tags: [Products]
      summary: Soft-delete a product
      description: Requires authentication and the `admin_rol` role.
      operationId: deleteProduct
      security:
        - tokenJWT: []
      parameters:
        - $ref: '#/components/parameters/Id'
      responses:
        '200':
          description: Product deactivated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  producto:
                    $ref: '#/components/schemas/Product'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'

  /buscar/{coleccion}/{termino}:
    get:
      tags: [Search]
      summary: Search a collection
      description: |
        Searches by MongoDB identifier or text. For users, it searches by name
        or email; for categories and products, by name. Text searches only
        include active records.
      operationId: search
      parameters:
        - name: coleccion
          in: path
          required: true
          description: Collection in which the search will be performed.
          schema:
            type: string
            enum: [usuarios, categorias, productos]
        - name: termino
          in: path
          required: true
          description: Text or MongoDB identifier to search for.
          schema:
            type: string
          example: notebook
      responses:
        '200':
          description: Results from the selected collection.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResults'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalError'

components:
  securitySchemes:
    tokenJWT:
      type: apiKey
      in: header
      name: x-token
      description: JWT obtained through `POST /auth/login`.

  parameters:
    Id:
      name: id
      in: path
      required: true
      description: MongoDB identifier of the resource.
      schema:
        type: string
        pattern: '^[a-fA-F0-9]{24}$'
      example: 65ea9ee3c8517efafa8658da
    Limite:
      name: limite
      in: query
      description: Maximum number of results.
      schema:
        type: integer
        default: 5
        minimum: 0
    Desde:
      name: desde
      in: query
      description: Number of results to skip from the beginning.
      schema:
        type: integer
        default: 0
        minimum: 0
    Limit:
      name: limit
      in: query
      description: Maximum number of products.
      schema:
        type: integer
        default: 10
        minimum: 0
    From:
      name: from
      in: query
      description: Number of products to skip from the beginning.
      schema:
        type: integer
        default: 0
        minimum: 0

  responses:
    BadRequest:
      description: Invalid data, nonexistent identifier, or violated business rule.
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/ErrorMessage'
              - $ref: '#/components/schemas/ValidationErrors'
    Unauthorized:
      description: The token is missing or invalid, or the user does not have the required role.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
    Forbidden:
      description: The authenticated user is not allowed to perform the action.
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/ErrorMessage'
              - $ref: '#/components/schemas/Error'
    NotFound:
      description: The related resource does not exist.
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/ErrorMessage'
              - $ref: '#/components/schemas/Error'
    InternalError:
      description: Unexpected server error.
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/ErrorMessage'
              - $ref: '#/components/schemas/Error'

  schemas:
    LoginRequest:
      type: object
      required: [correo, password]
      additionalProperties: false
      properties:
        correo:
          type: string
          format: email
          example: usuario@example.com
        password:
          type: string
          format: password
          example: password123
    LoginResponse:
      type: object
      required: [user, token]
      properties:
        user:
          $ref: '#/components/schemas/User'
        token:
          type: string
          description: JWT to send in the `x-token` header.
          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
    CreateUserRequest:
      type: object
      required: [nombre, correo, password, rol]
      properties:
        nombre:
          type: string
          minLength: 1
          example: Jane Doe
        correo:
          type: string
          format: email
          example: ana@example.com
        password:
          type: string
          format: password
          minLength: 6
          example: secreto123
        rol:
          type: string
          description: MongoDB identifier of the role.
          pattern: '^[a-fA-F0-9]{24}$'
          example: 649bc31bf9cb9aec95f19c21
    UpdateUserRequest:
      type: object
      description: Only the provided profile fields are updated. Role and account status cannot be changed through this endpoint.
      properties:
        nombre:
          type: string
          example: Jane Doe
        correo:
          type: string
          format: email
        password:
          type: string
          format: password
        img:
          type: string
    User:
      type: object
      properties:
        nombre:
          type: string
          example: Jane Doe
        correo:
          type: string
          format: email
          example: ana@example.com
        img:
          type: string
          nullable: true
        rol:
          oneOf:
            - type: string
            - $ref: '#/components/schemas/Role'
        estado:
          type: boolean
          example: true
        uID:
          type: string
          pattern: '^[a-fA-F0-9]{24}$'
          example: 649bc31bf9cb9aec95f19c21
    Role:
      type: object
      additionalProperties: true
      properties:
        _id:
          type: string
        rol:
          type: string
          example: admin_rol
    CategoryRequest:
      type: object
      required: [nombre]
      properties:
        nombre:
          type: string
          minLength: 1
          example: Technology
    Category:
      type: object
      properties:
        _id:
          type: string
          pattern: '^[a-fA-F0-9]{24}$'
        nombre:
          type: string
          example: TECHNOLOGY
        estado:
          type: boolean
          example: true
        usuario:
          type: string
          pattern: '^[a-fA-F0-9]{24}$'
    ExpandedCategory:
      allOf:
        - $ref: '#/components/schemas/Category'
        - type: object
          properties:
            usuario:
              $ref: '#/components/schemas/User'
    CreateProductRequest:
      type: object
      required: [nombre, categoria]
      properties:
        nombre:
          type: string
          minLength: 1
          example: Notebook
        categoria:
          type: string
          pattern: '^[a-fA-F0-9]{24}$'
          example: 65ea9ee3c8517efafa8658da
        precio:
          type: number
          default: 0
          example: 1250.5
        descripcion:
          type: string
          example: Laptop for professional use.
    UpdateProductRequest:
      type: object
      required: [nombre]
      properties:
        nombre:
          type: string
          minLength: 1
          example: Notebook Pro
        usuario:
          type: string
          pattern: '^[a-fA-F0-9]{24}$'
        categoria:
          type: string
          pattern: '^[a-fA-F0-9]{24}$'
        precio:
          type: number
        descripcion:
          type: string
        disponible:
          type: boolean
    Product:
      type: object
      properties:
        _id:
          type: string
          pattern: '^[a-fA-F0-9]{24}$'
        nombre:
          type: string
          example: NOTEBOOK
        usuario:
          type: string
          pattern: '^[a-fA-F0-9]{24}$'
        precio:
          type: number
          example: 1250.5
        categoria:
          type: string
          pattern: '^[a-fA-F0-9]{24}$'
        descripcion:
          type: string
        disponible:
          type: boolean
          default: true
    ExpandedProduct:
      allOf:
        - $ref: '#/components/schemas/Product'
        - type: object
          properties:
            usuario:
              $ref: '#/components/schemas/User'
            categoria:
              $ref: '#/components/schemas/Category'
    SearchResults:
      type: object
      required: [results]
      properties:
        results:
          type: array
          items:
            oneOf:
              - $ref: '#/components/schemas/User'
              - $ref: '#/components/schemas/Category'
              - $ref: '#/components/schemas/Product'
    ErrorMessage:
      type: object
      required: [msg]
      properties:
        msg:
          type: string
          example: Invalid authentication token.
    Error:
      type: object
      required: [error]
      properties:
        error:
          type: string
          example: Product not found.
    ValidationErrors:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                example: field
              value:
                nullable: true
              msg:
                type: string
                example: A valid ID is required.
              path:
                type: string
                example: id
              location:
                type: string
                example: params