Swagger YAML.yaml

openapi: 3.0.0
info:
  title: Comunidad de Vinos API
  description: API para la gestión y recomendación de vinos en una comunidad online
  version: 1.0.0
servers:
  # Added by API Auto Mocking Plugin
  - description: SwaggerHub API Auto Mocking
    url: https://virtserver.swaggerhub.com/LUISAZOFRABEGARA/SOS/1.0.0
  - url: https://example.com/api
paths:
  /usuarios:
    get:
      summary: Obtener todos los usuarios
      description: Devuelve una lista paginada de todos los usuarios en la aplicación
      parameters:
        - in: query
          name: page
          description: Número de página
          schema:
            type: integer
        - in: query
          name: name
          description: Filtro por nombre
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Usuario'
    post:
      summary: Añadir un usuario nuevo
      description: Añade un nuevo usuario a la comunidad
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UsuarioInput'
      responses:
        '201':
          description: Usuario creado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Usuario'
        '400':
          description: Datos incorrectos
  /usuarios/{id}:
    get:
      summary: Obtener datos de un usuario
      description: Devuelve los datos básicos de un usuario dado su ID
      parameters:
        - in: path
          name: id
          description: ID del usuario
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Usuario'
    put:
      summary: Actualizar datos de un usuario
      description: Actualiza los datos básicos de un usuario
      parameters:
        - in: path
          name: id
          description: ID del usuario
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UsuarioInput'
      responses:
        '200':
          description: Usuario actualizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Usuario'
        '400':
          description: Datos incorrectos
    delete:
      summary: Borrar un usuario
      description: Borra un usuario de la comunidad
      parameters:
        - in: path
          name: id
          description: ID del usuario
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Usuario borrado
  
  /usuarios/{id}/vinos:
    get:
      summary: Obtener la lista de vinos de un usuario
      description: Devuelve una lista paginada de vinos de un usuario
      parameters:
        - in: path
          name: id
          description: ID del usuario
          required: true
          schema:
            type: string
        - in: query
          name: page
          description: Número de página
          schema:
            type: integer
        - in: query
          name: sortBy
          description: Campo para ordenar la lista (e.g., fecha_adicion)
          schema:
            type: string
        - in: query
          name: sortOrder
          description: Orden ascendente o descendente (asc o desc)
          schema:
            type: string
        - in: query
          name: tipo_vino
          description: Tipo de vino
          schema:
            type: string
        - in: query
          name: tipos_uva
          description: Tipo(s) de uva
          schema:
            type: string
        - in: query
          name: denominacion_origen
          description: Denominación de origen
          schema:
            type: string
        - in: query
          name: anada
          description: Añada del vino
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Vino'
    post:
      summary: Añadir un nuevo vino a la lista de un usuario
      description: Añade un nuevo vino a la lista de vinos de un usuario
      parameters:
        - in: path
          name: id
          description: ID del usuario
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VinoInput'
      responses:
        '201':
          description: Vino añadido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Vino'
        '400':
          description: Datos incorrectos
  /usuarios/{id}/vinos/{vinoId}:
    put:
      summary: Modificar la puntuación de un vino
      description: Modifica la puntuación de un vino en la lista de un usuario
      parameters:
        - in: path
          name: id
          description: ID del usuario
          required: true
          schema:
            type: string
        - in: path
          name: vinoId
          description: ID del vino
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PuntuacionInput'
      responses:
        '200':
          description: Puntuación actualizada
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Vino'
        '400':
          description: Puntuación inválida
    delete:
      summary: Eliminar un vino de la lista
      description: Elimina un vino de la lista de un usuario
      parameters:
        - in: path
          name: id
          description: ID del usuario
          required: true
          schema:
            type: string
        - in: path
          name: vinoId
          description: ID del vino
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Vino eliminado
  /usuarios/{id}/seguidores:
    get:
      summary: Obtener la lista de seguidores de un usuario
      description: Devuelve una lista paginada de los seguidores de un usuario
      parameters:
        - in: path
          name: id
          description: ID del usuario
          required: true
          schema:
            type: string
        - in: query
          name: nombre
          description: Filtrar por nombre del seguidor
          schema:
            type: string
        - in: query
          name: limit
          description: Limitar la cantidad de resultados
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Usuario'
    put:
      summary: Añadir seguidor a un usuario
      description: Añade un usuario como seguidor al usuario especificado por {id}
      parameters:
        - in: path
          name: id
          description:  ID del usuario que será seguido

          required: true
          schema:
            type: string
        - in: query
          name: seguidorId
          description: ID del usuario que desea seguir al usuario identificado por {id}.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Seguidor añadido exitosamente
        '404':
          description: No se encontró el usuario o el seguidor
  /usuarios/{id}/seguidores/{seguidorId}:
    delete:
      summary: Eliminar un seguidor de la lista
      description: Elimina un seguidor de la lista de seguidores de un usuario
      parameters:
        - in: path
          name: id
          description: ID del usuario
          required: true
          schema:
            type: string
        - in: path
          name: seguidorId
          description: ID del seguidor a eliminar
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Seguidor eliminado
        '404':
          description: No se encontró el usuario o el seguidor
  /usuarios/{id}/recomendaciones:
    get:
      summary: Obtener sistema de recomendaciones personalizado para un usuario
      description: Devuelve la información del usuario, sus 5 últimos vinos añadidos, 5 vinos con mayor puntuación y los 5 mejores vinos de sus amigos.
      parameters:
        - in: path
          name: id
          description: ID del usuario
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Recomendaciones'
components:
  schemas:
    Usuario:
      type: object
      properties:
        id:
          type: string
          description: Identificador único del usuario
        nombre:
          type: string
          description: Nombre del usuario
        fecha_nacimiento:
          type: string
          format: date
          description: Fecha de nacimiento del usuario
        correo:
          type: string
          format: email
          description: Correo electrónico del usuario
    UsuarioInput:
      type: object
      properties:
        nombre:
          type: string
          description: Nombre del usuario
        fecha_nacimiento:
          type: string
          format: date
          description: Fecha de nacimiento del usuario
        correo:
          type: string
          format: email
          description: Correo electrónico del usuario
    Vino:
      type: object
      properties:
        id:
          type: string
          description: Identificador único del vino
        nombre_botella:
          type: string
          description: Nombre de la botella de vino
        bodega:
          type: string
          description: Bodega a la que pertenece el vino
        anada:
          type: integer
          description: Añada del vino
        denominacion_origen:
          type: string
          description: Denominación de origen del vino
        tipo_vino:
          type: string
          description: Tipo de vino (tinto, blanco, rosado, etc.)
        tipos_uva:
          type: array
          items:
            type: object
            properties:
              nombre:
                type: string
                description: Nombre del tipo de uva
              porcentaje:
                type: number
                description: Porcentaje del tipo de uva en el vino
    PuntuacionInput:
      type: object
      properties:
        puntuacion:
          type: integer
          minimum: 0
          maximum: 10
          description: Puntuación del vino
    VinoInput:
      type: object
      properties:
        nombre_botella:
          type: string
          description: Nombre de la botella de vino
        bodega:
          type: string
          description: Bodega a la que pertenece el vino
        anada:
          type: integer
          description: Añada del vino
        denominacion_origen:
          type: string
          description: Denominación de origen del vino
        tipo_vino:
          type: string
          description: Tipo de vino (tinto, blanco, rosado, etc.)
        tipos_uva:
          type: array
          items:
            type: object
            properties:
              nombre:
                type: string
                description: Nombre del tipo de uva
              porcentaje:
                type: number
                description: Porcentaje del tipo de uva en el vino
    Recomendaciones:
      type: object
      properties:
        usuario:
          $ref: '#/components/schemas/Usuario'
        ultimos_vinos:
          type: array
          items:
            $ref: '#/components/schemas/Vino'
        vinos_mejor_puntuados:
          type: array
          items:
            $ref: '#/components/schemas/Vino'
        mejores_vinos_amigos:
          type: array
          items:
            $ref: '#/components/schemas/Vino'