info:
  version: 0.18.5
  title: IT Academy Wiki
  description: Our app implements a Wiki to be used as a knowledge base by the
    students of the Barcelona Activa's IT Academy
openapi: 3.0.0
components:
  headers:
    Set-Cookie:
      schema:
        type: string
        example: token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiJjbGdieTNyemYwMDAweG44eDdzeXJvMnc2IiwiaWF0IjoxNjgxMjEyNzAzLCJleHAiOjE2ODEyOTkxMDN9.G1F5XQLYu0uwxnJDx_qDUV3avIUPxHb3Ld-XZYvUfNM;
          path=/; httponly
        description: Sets the JWT session cookie
  securitySchemes:
    cookieAuth:
      type: apiKey
      in: cookie
      name: token
  schemas:
    DniError:
      type: object
      properties:
        message:
          type: string
          example: dni already exists
      required:
        - message
    EmailError:
      type: object
      properties:
        message:
          type: string
          example: email already exists
      required:
        - message
    InputError:
      type: object
      properties:
        message:
          type: string
          example: Input is not a string
      required:
        - message
    MissingTokenError:
      type: object
      properties:
        message:
          type: string
          example: Missing token
      required:
        - message
    InvalidTokenError:
      type: object
      properties:
        message:
          type: string
          example: Token is not valid
      required:
        - message
    ForbiddenError:
      type: object
      properties:
        message:
          type: string
          example: Only active users can login
      required:
        - message
    MissingUserError:
      type: object
      properties:
        message:
          type: string
          example: User not found
      required:
        - message
    UpstreamServiceFail:
      type: object
      properties:
        message:
          type: string
          example: Upstream service failed to respond with the required data
      required:
        - message
    ServiceUnavailableError:
      type: object
      properties:
        message:
          type: string
          example: Service Unavailable
      required:
        - message
    ValidationError:
      type: object
      properties:
        message:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                example: invalid_string
              message:
                type: string
                example: Invalid
              path:
                type: array
                items:
                  type: string
                  example: dni
              validation:
                type: string
                example: regex
              expected:
                type: string
                example: string
              received:
                type: string
                example: undefined
              options:
                type: array
                items:
                  type: string
                example:
                  - BLOG
                  - VIDEO
                  - TUTORIAL
            required:
              - code
              - message
              - path
      required:
        - message
  parameters: {}
paths:
  /api/v1/auth/login:
    post:
      tags:
        - auth
      operationId: postLogin
      description: Takes a DNI and a password and returns a session cookie
      summary: Logs in a user
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                dni:
                  type: string
                password:
                  type: string
                  minLength: 8
              required:
                - dni
                - password
      responses:
        "204":
          description: The user has been authenticated
          headers:
            Set-Cookie:
              $ref: "#/components/headers/Set-Cookie"
        "400":
          description: Zod validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValidationError"
        "401":
          description: User not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MissingUserError"
        "403":
          description: Forbidden error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ForbiddenError"
        "404":
          description: User not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MissingUserError"
        "422":
          description: Invalid password
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Invalid password
                required:
                  - message
        "503":
          description: The SSO server is not available.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ServiceUnavailableError"
                  - example: &a3
                      message: Service Unavailable
  /api/v1/auth/register:
    post:
      tags:
        - auth
      operationId: postRegister
      description: Takes a DNI, a password, a name and an email an registers a user to
        the system
      summary: Registers a new user
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  format: email
                  example: user@example.cat
                dni:
                  type: string
                itineraryId:
                  type: string
                  minLength: 1
                name:
                  type: string
                accept:
                  type: boolean
                  enum:
                    - true
                password:
                  type: string
                  minLength: 8
                  pattern: ^(?=.*[A-Za-z])(?=.*\d)[A-Za-z\d]*$
                confirmPassword:
                  type: string
                  minLength: 8
                  pattern: ^(?=.*[A-Za-z])(?=.*\d)[A-Za-z\d]*$
              required:
                - email
                - dni
                - itineraryId
                - name
                - accept
                - password
                - confirmPassword
              additionalProperties: false
      responses:
        "204":
          description: The user has been registered
        "400":
          description: Invalid input
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: "#/components/schemas/ValidationError"
                  - $ref: "#/components/schemas/DniError"
                  - $ref: "#/components/schemas/EmailError"
        "409":
          description: Conflict, data already exists.
        "500":
          description: Other error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Database error
                required:
                  - message
  /api/v1/auth/me:
    get:
      tags:
        - auth
      operationId: getMe
      description: Returns information of a logged in user. Token recieved in the
        login necessary.
      summary: Get user information
      security:
        - cookieAuth: []
      responses:
        "200":
          description: Token is valid and user information is returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  name:
                    type: string
                  dni:
                    type: string
                  email:
                    type: string
                    format: email
                    example: user@example.cat
                  role:
                    type: string
                    enum:
                      - ADMIN
                      - MENTOR
                      - REGISTERED
                  status:
                    type: string
                    enum:
                      - ACTIVE
                      - INACTIVE
                required:
                  - id
                  - dni
                  - email
                  - role
                  - status
        "401":
          description: Invalid token
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: "#/components/schemas/InvalidTokenError"
                  - $ref: "#/components/schemas/MissingTokenError"
        "404":
          description: User not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MissingUserError"
        "500":
          description: Other error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Database error
                required:
                  - message
  /api/v1/auth/logout:
    get:
      tags:
        - auth
      operationId: getLogout
      description: Deletes cookie and logouts user
      summary: Logs out user
      responses:
        "204":
          description: User has been logged out successfully
  /api/v1/categories:
    get:
      tags:
        - categories
      operationId: listCategories
      description: Get all categories saved in the database
      summary: Get all categories
      responses:
        "200":
          description: Categories fetched
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                    name:
                      type: string
                      example: Javascript
                    slug:
                      type: string
                      example: javascript
                  required:
                    - id
                    - name
                    - slug
    post:
      tags:
        - categories
      operationId: postCategories
      description: Creates a new category. The requestor has to be logged in and with
        role ADMIN.
      summary: Creates a new category.
      security:
        - cookieAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: React
              required:
                - name
      responses:
        "204":
          description: New category created succesfully.
        "401":
          description: Invalid token
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: "#/components/schemas/InvalidTokenError"
                  - $ref: "#/components/schemas/MissingTokenError"
        "403":
          description: Forbidden. Acces denied.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ForbiddenError"
                  - example: &a1
                      message: Access denied. You don't have permissions
        "500":
          description: Other error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Database error
                required:
                  - message
  "/api/v1/categories/id/{id}":
    patch:
      tags:
        - categories
      operationId: patchCategories
      summary: Patch a category by its ID.
      description: Modifies an existing category. The requestor has to be logged in
        and with role ADMIN.
      security:
        - cookieAuth: []
      parameters:
        - in: path
          name: categoryId
          schema:
            type: string
          required: true
          description: ID of the category to modify
          example: clnwzimjp0000h88ktz1ibtq5
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: React
              required:
                - name
      responses:
        "204":
          description: Category modified succesfully.
        "401":
          description: Invalid token
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: "#/components/schemas/InvalidTokenError"
                  - $ref: "#/components/schemas/MissingTokenError"
        "403":
          description: Forbidden. Acces denied.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ForbiddenError"
                  - example: *a1
        "404":
          description: Category not found
        "500":
          description: Other error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Database error
                required:
                  - message
  /api/v1/topics:
    get:
      tags:
        - topics
      operationId: listTopics
      description: Returns a list of all topics. Filter by category id or category
        slug possible. If both filters are sent, will only search by category
        id.
      summary: Returns topics. Filter by category possible.
      parameters:
        - in: query
          name: categoryId
          schema:
            type: string
          required: false
        - in: query
          name: slug
          schema:
            type: string
            example: javascript
          required: false
      responses:
        "200":
          description: Topics retrieved succesfully,
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                    name:
                      type: string
                      example: React Props
                    slug:
                      type: string
                      example: react-props
                    categoryId:
                      type: string
                  required:
                    - id
                    - name
                    - categoryId
        "404":
          description: Category not found.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/MissingUserError"
                  - example:
                      message: Category not found
    post:
      tags:
        - topics
      operationId: postTopics
      description: Creates a new topic. The requestor has to be logged in and with
        role MENTOR or higher.
      summary: Creates a new topic.
      security:
        - cookieAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: React Props
                categoryId:
                  type: string
              required:
                - name
                - categoryId
      responses:
        "204":
          description: New topic created succesfully.
        "401":
          description: Invalid token
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: "#/components/schemas/InvalidTokenError"
                  - $ref: "#/components/schemas/MissingTokenError"
        "403":
          description: Forbidden. Acces denied.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ForbiddenError"
                  - example: *a1
        "500":
          description: Other error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Database error
                required:
                  - message
    patch:
      tags:
        - topics
      operationId: patchTopics
      description: Modifies an existing topic. The requestor has to be logged in and
        with role MENTOR or higher.
      summary: Patch a topic.
      security:
        - cookieAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                name:
                  type: string
                  example: Advanced React Props
                categoryId:
                  type: string
              required:
                - id
              additionalProperties: false
      responses:
        "204":
          description: Topic successfully modified.
        "401":
          description: Invalid token
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: "#/components/schemas/InvalidTokenError"
                  - $ref: "#/components/schemas/MissingTokenError"
        "403":
          description: Forbidden. Acces denied.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ForbiddenError"
                  - example: *a1
        "404":
          description: Topic not found
        "500":
          description: Other error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Database error
                required:
                  - message
  "/api/v1/resources/favorites/{categorySlug}":
    get:
      tags:
        - resources
      operationId: listFavoritesResources
      description: Retrieves the users favorite resources when logged in
      summary: Returns favorite resources by user and category
      parameters:
        - in: path
          name: categorySlug
          schema:
            type: string
            minLength: 1
          required: true
      responses:
        "200":
          description: Favorite resources retrieved successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                    title:
                      type: string
                      example: My Resource in Javascript
                    slug:
                      type: string
                      example: my-resource-in-javascript
                    description:
                      type: string
                      nullable: true
                      example: Lorem ipsum javascript
                    url:
                      type: string
                      format: uri
                      example: https://tutorials.cat/learn/javascript
                    resourceType:
                      type: string
                      enum: &a2
                        - BLOG
                        - VIDEO
                        - TUTORIAL
                    categoryId:
                      type: string
                      example: clocr0bi20000h8vwipfbazso
                    createdAt:
                      anyOf:
                        - type: string
                          format: date-time
                        - type: string
                    updatedAt:
                      anyOf:
                        - type: string
                          format: date-time
                        - type: string
                    user:
                      type: object
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                      required:
                        - id
                    isAuthor:
                      type: boolean
                    voteCount:
                      type: object
                      properties:
                        upvote:
                          type: integer
                          minimum: 0
                          example: 14
                        downvote:
                          type: integer
                          minimum: 0
                          example: 2
                        total:
                          type: integer
                          example: 12
                        userVote:
                          type: integer
                          minimum: -1
                          maximum: 1
                      required:
                        - upvote
                        - downvote
                        - total
                        - userVote
                    topics:
                      type: array
                      items:
                        type: object
                        properties:
                          topic:
                            type: object
                            properties:
                              id:
                                type: string
                              name:
                                type: string
                                example: React Props
                              slug:
                                type: string
                                example: react-props
                              categoryId:
                                type: string
                              createdAt:
                                anyOf:
                                  - type: string
                                    format: date-time
                                  - type: string
                              updatedAt:
                                anyOf:
                                  - type: string
                                    format: date-time
                                  - type: string
                            required:
                              - id
                              - name
                              - categoryId
                              - createdAt
                              - updatedAt
                        required:
                          - topic
                  required:
                    - id
                    - title
                    - slug
                    - url
                    - resourceType
                    - categoryId
                    - createdAt
                    - updatedAt
                    - user
                    - isAuthor
                    - voteCount
                    - topics
        "401":
          description: Invalid token
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: "#/components/schemas/InvalidTokenError"
                  - $ref: "#/components/schemas/MissingTokenError"
        "404":
          description: User not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MissingUserError"
  /api/v1/resources:
    get:
      tags:
        - resources
      operationId: listResources
      description: Returns a collection of resources. Filters by resource type, topic
        name and category slug are optional. Resources that match all filters
        are fetched.
      summary: Returns a collection of resources
      parameters:
        - in: query
          name: categorySlug
          schema:
            type: string
            example: react
          required: false
          description: Slug of the category for which to retrieve resources
          example: react
        - in: query
          name: topicSlug
          schema:
            type: string
            example: jsx
          required: false
          description: Slug of the topic for which to retrieve resources
          example: jsx
        - in: query
          name: resourceTypes
          schema:
            type: array
            uniqueItems: true
            items:
              type: string
              enum:
                - BLOG
                - VIDEO
                - TUTORIAL
          required: false
          description: Resource types to filter by
        - in: query
          name: topic
          schema:
            type: string
            example: cln2u09xo0037s6wvbf6t9jfg
          required: false
          description: ID string of the topic for which to retrieve resources. If not
            provided, resources for ALL topics are fetched.
        - in: query
          name: status
          schema:
            type: array
            uniqueItems: true
            items:
              type: string
              enum:
                - SEEN
                - NOT_SEEN
          required: false
          description: Status to filter by
        - in: query
          name: search
          schema:
            type: string
          required: false
          description: Search query to filter by
          example: tailwind
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                    title:
                      type: string
                      example: My Resource in Javascript
                    slug:
                      type: string
                      example: my-resource-in-javascript
                    description:
                      type: string
                      nullable: true
                      example: Lorem ipsum javascript
                    url:
                      type: string
                      format: uri
                      example: https://tutorials.cat/learn/javascript
                    resourceType:
                      type: string
                      enum: *a2
                    categoryId:
                      type: string
                      example: clocr0bi20000h8vwipfbazso
                    createdAt:
                      anyOf:
                        - type: string
                          format: date-time
                        - type: string
                    updatedAt:
                      anyOf:
                        - type: string
                          format: date-time
                        - type: string
                    user:
                      type: object
                      properties:
                        name:
                          type: string
                        id:
                          type: string
                      required:
                        - id
                    topics:
                      type: array
                      items:
                        type: object
                        properties:
                          topic:
                            type: object
                            properties:
                              id:
                                type: string
                              name:
                                type: string
                                example: React Props
                              slug:
                                type: string
                                example: react-props
                              categoryId:
                                type: string
                              createdAt:
                                anyOf:
                                  - type: string
                                    format: date-time
                                  - type: string
                              updatedAt:
                                anyOf:
                                  - type: string
                                    format: date-time
                                  - type: string
                            required:
                              - id
                              - name
                              - categoryId
                              - createdAt
                              - updatedAt
                        required:
                          - topic
                    voteCount:
                      type: object
                      properties:
                        upvote:
                          type: integer
                          minimum: 0
                          example: 14
                        downvote:
                          type: integer
                          minimum: 0
                          example: 2
                        total:
                          type: integer
                          example: 12
                        userVote:
                          type: integer
                          minimum: -1
                          maximum: 1
                      required:
                        - upvote
                        - downvote
                        - total
                        - userVote
                    isFavorite:
                      type: boolean
                      default: false
                  required:
                    - id
                    - title
                    - slug
                    - url
                    - resourceType
                    - categoryId
                    - createdAt
                    - updatedAt
                    - user
                    - topics
                    - voteCount
                    - isFavorite
        "400":
          description: Zod validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValidationError"
        "401":
          description: Invalid token
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: "#/components/schemas/InvalidTokenError"
                  - $ref: "#/components/schemas/MissingTokenError"
    post:
      tags:
        - resources
      operationId: postResources
      description: Allows a logged in user to post a resource.
      summary: Post a resource
      security:
        - cookieAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                  example: My Resource in Javascript
                description:
                  type: string
                  nullable: true
                  example: Lorem ipsum javascript
                url:
                  type: string
                  format: uri
                  example: https://tutorials.cat/learn/javascript
                resourceType:
                  type: string
                  enum: *a2
                categoryId:
                  type: string
                  example: clocr0bi20000h8vwipfbazso
                topics:
                  type: array
                  items:
                    type: string
                    example: clocr0bpv000ah8vwnfvpo24p
              required:
                - title
                - url
                - resourceType
                - categoryId
                - topics
      responses:
        "204":
          description: Resource has been posted
        "401":
          description: Invalid token
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: "#/components/schemas/InvalidTokenError"
                  - $ref: "#/components/schemas/MissingTokenError"
    patch:
      tags:
        - resources
      operationId: patchResources
      description: Allows a logged in user to modify his resources.
      summary: Patch a resource
      security:
        - cookieAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                title:
                  type: string
                description:
                  type: string
                url:
                  type: string
                topicId:
                  type: string
                resourceType:
                  type: string
                  enum:
                    - BLOG
                    - VIDEO
                    - TUTORIAL
              required:
                - id
              additionalProperties: false
      responses:
        "204":
          description: Resource has been modified
        "401":
          description: Invalid token
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: "#/components/schemas/InvalidTokenError"
                  - $ref: "#/components/schemas/MissingTokenError"
        "404":
          description: Not found
  /api/v1/resources/generate-description:
    post:
      tags:
        - resources
      operationId: postResourcesGenerateDescription
      description: Allows an authenticated user to generate a description for a
        resource. Requires language as a query parameter and title, url, and
        topic in the request body.
      summary: Generates a description for a resource
      security:
        - cookieAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                  format: uri
                  example: https://tutorials.cat/learn/javascript
                title:
                  type: string
                  example: My Resource in Javascript
                topic:
                  type: string
                  example: Web Development
                language:
                  type: string
                  enum:
                    - en
                    - es
                    - ca
                  example: en
              required:
                - url
                - title
                - topic
                - language
      responses:
        "200":
          description: A description for the resource is generated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  description:
                    type: string
                required:
                  - description
        "400":
          description: Error fetching data from external API
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Error fetching data from external API
                required:
                  - error
        "401":
          description: Invalid token
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: "#/components/schemas/InvalidTokenError"
                  - $ref: "#/components/schemas/MissingTokenError"
        "422":
          description: Missing required parameters
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValidationError"
        "500":
          description: An error occured while getting the description
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: An error occured while getting the description
                required:
                  - message
  "/api/v1/seen/{resourceId}":
    post:
      tags:
        - seen
      operationId: postUserSeenResourcesById
      description: Allows a logged in user to mark a resource as viewed.
      summary: Mark a resource as viewed
      security:
        - cookieAuth: []
      parameters:
        - in: path
          name: resourceId
          schema:
            type: string
            minLength: 1
            example: cln2u09xo0037s6wvbf6t9jfg
          required: true
          description: ID of the resource to be retrieved.
      responses:
        "204":
          description: Resource marked as viewed
        "401":
          description: Invalid token
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: "#/components/schemas/InvalidTokenError"
                  - $ref: "#/components/schemas/MissingTokenError"
  "/api/v1/resources/{resourceId}":
    get:
      tags:
        - resources
      operationId: getResourcesById
      summary: Returns a resource by its ID
      description: Takes in a valid resource ID and returns the resource related to it.
      parameters:
        - in: path
          name: resourceId
          schema:
            type: string
            minLength: 1
            example: cln2u09xo0037s6wvbf6t9jfg
          required: true
          description: ID of the resource to be retrieved.
      responses:
        "200":
          description: Resource found
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  title:
                    type: string
                    example: My Resource in Javascript
                  slug:
                    type: string
                    example: my-resource-in-javascript
                  description:
                    type: string
                    nullable: true
                    example: Lorem ipsum javascript
                  url:
                    type: string
                    format: uri
                    example: https://tutorials.cat/learn/javascript
                  resourceType:
                    type: string
                    enum: *a2
                  categoryId:
                    type: string
                    example: clocr0bi20000h8vwipfbazso
                  createdAt:
                    anyOf:
                      - type: string
                        format: date-time
                      - type: string
                  updatedAt:
                    anyOf:
                      - type: string
                        format: date-time
                      - type: string
                  user:
                    type: object
                    properties:
                      name:
                        type: string
                      id:
                        type: string
                    required:
                      - id
                  topics:
                    type: array
                    items:
                      type: object
                      properties:
                        topic:
                          type: object
                          properties:
                            id:
                              type: string
                            name:
                              type: string
                              example: React Props
                            slug:
                              type: string
                              example: react-props
                            categoryId:
                              type: string
                            createdAt:
                              anyOf:
                                - type: string
                                  format: date-time
                                - type: string
                            updatedAt:
                              anyOf:
                                - type: string
                                  format: date-time
                                - type: string
                          required:
                            - id
                            - name
                            - categoryId
                            - createdAt
                            - updatedAt
                      required:
                        - topic
                  voteCount:
                    type: object
                    properties:
                      upvote:
                        type: integer
                        minimum: 0
                        example: 14
                      downvote:
                        type: integer
                        minimum: 0
                        example: 2
                      total:
                        type: integer
                        example: 12
                      userVote:
                        type: integer
                        minimum: -1
                        maximum: 1
                    required:
                      - upvote
                      - downvote
                      - total
                      - userVote
                  isFavorite:
                    type: boolean
                    default: false
                required:
                  - id
                  - title
                  - slug
                  - url
                  - resourceType
                  - categoryId
                  - createdAt
                  - updatedAt
                  - user
                  - topics
                  - voteCount
                  - isFavorite
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ValidationError"
                  - example:
                      message:
                        - code: invalid_string
                          validation: cuid
                          path:
                            - params
                            - resourceId
                          message: Invalid cuid
        "404":
          description: Resource not found
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/MissingUserError"
                  - example:
                      message: Resource not found
  /api/v1/resources/me:
    get:
      tags:
        - resources
      operationId: listUserMeResources
      summary: Get resources by logged in user
      description: Returns all the posted resources by a logged in user. In addition,
        if categorySlug query provided, returns only the resources posted in
        that category.
      security:
        - cookieAuth: []
      parameters:
        - in: query
          name: categorySlug
          schema:
            type: string
            example: react
          required: false
      responses:
        "200":
          description: All resources posted by user are returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  resources:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        title:
                          type: string
                          example: My Resource in Javascript
                        slug:
                          type: string
                          example: my-resource-in-javascript
                        description:
                          type: string
                          nullable: true
                          example: Lorem ipsum javascript
                        url:
                          type: string
                          format: uri
                          example: https://tutorials.cat/learn/javascript
                        resourceType:
                          type: string
                          enum: *a2
                        categoryId:
                          type: string
                          example: clocr0bi20000h8vwipfbazso
                        createdAt:
                          anyOf:
                            - type: string
                              format: date-time
                            - type: string
                        updatedAt:
                          anyOf:
                            - type: string
                              format: date-time
                            - type: string
                        user:
                          type: object
                          properties:
                            name:
                              type: string
                            id:
                              type: string
                          required:
                            - id
                        topics:
                          type: array
                          items:
                            type: object
                            properties:
                              topic:
                                type: object
                                properties:
                                  id:
                                    type: string
                                  name:
                                    type: string
                                    example: React Props
                                  slug:
                                    type: string
                                    example: react-props
                                  categoryId:
                                    type: string
                                  createdAt:
                                    anyOf:
                                      - type: string
                                        format: date-time
                                      - type: string
                                  updatedAt:
                                    anyOf:
                                      - type: string
                                        format: date-time
                                      - type: string
                                required:
                                  - id
                                  - name
                                  - categoryId
                                  - createdAt
                                  - updatedAt
                            required:
                              - topic
                        voteCount:
                          type: object
                          properties:
                            upvote:
                              type: integer
                              minimum: 0
                              example: 14
                            downvote:
                              type: integer
                              minimum: 0
                              example: 2
                            total:
                              type: integer
                              example: 12
                            userVote:
                              type: integer
                              minimum: -1
                              maximum: 1
                          required:
                            - upvote
                            - downvote
                            - total
                            - userVote
                        isFavorite:
                          type: boolean
                          default: false
                      required:
                        - id
                        - title
                        - slug
                        - url
                        - resourceType
                        - categoryId
                        - createdAt
                        - updatedAt
                        - user
                        - topics
                        - voteCount
                        - isFavorite
                required:
                  - resources
        "401":
          description: Invalid token
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: "#/components/schemas/InvalidTokenError"
                  - $ref: "#/components/schemas/MissingTokenError"
        "404":
          description: User not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MissingUserError"
  "/api/v1/vote/{resourceId}":
    get:
      tags:
        - vote
      operationId: listVotes
      description: Retrieve a detailed vote count for a specified resource, including
        the number of upvotes, downvotes, and the overall vote balance.
      summary: Fetch detailed vote statistics for a resource.
      parameters:
        - in: path
          name: resourceId
          schema:
            type: string
            minLength: 1
            example: cln2u09xo0037s6wvbf6t9jfg
          required: true
          description: ID of the resource to be retrieved.
      responses:
        "200":
          description: Successfully retrieved detailed vote statistics for the specified
            resource.
          content:
            application/json:
              schema:
                type: object
                properties:
                  upvote:
                    type: integer
                    minimum: 0
                    example: 14
                  downvote:
                    type: integer
                    minimum: 0
                    example: 2
                  total:
                    type: integer
                    example: 12
                  userVote:
                    type: integer
                    minimum: -1
                    maximum: 1
                required:
                  - upvote
                  - downvote
                  - total
                  - userVote
        "401":
          description: Invalid token
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: "#/components/schemas/InvalidTokenError"
                  - $ref: "#/components/schemas/MissingTokenError"
        "404":
          description: Resource not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Resource not found
                required:
                  - error
  /api/v1/vote:
    put:
      tags:
        - vote
      description: Allows a user to vote for a resource. Vote can be "up", "down"  or
        "cancel" to cancel a previous vote.
      summary: Allows a user to vote for a resource.
      security:
        - cookieAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                resourceId:
                  type: string
                  description: ID of the resource to vote
                vote:
                  type: string
                  enum:
                    - up
                    - down
                    - cancel
                  description: Upvote, downvote or cancel a previous vote.
              required:
                - resourceId
                - vote
      responses:
        "204":
          description: Vote was sent and stored successfully.
        "400":
          description: Validation error. Either resourceId or vote are not correct
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValidationError"
        "401":
          description: Invalid token
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: "#/components/schemas/InvalidTokenError"
                  - $ref: "#/components/schemas/MissingTokenError"
        "404":
          description: User or resource not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - User not found
                      - Resource not found
                required:
                  - message
  /api/v1/types:
    get:
      tags:
        - types
      operationId: listResourceTypes
      description: Returns an array of all the resource types
      summary: Returns resource types
      responses:
        "200":
          description: types fetched
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                  enum:
                    - BLOG
                    - VIDEO
                    - TUTORIAL
  /api/v1/users:
    get:
      tags:
        - users
      operationId: listUsers
      description: Returns information of all users. User must be ADMIN and logged in.
      summary: Get all users
      security:
        - cookieAuth: []
      responses:
        "200":
          description: Token is valid and info of all users is returned.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                    email:
                      type: string
                      format: email
                      example: user@example.cat
                    dni:
                      type: string
                    name:
                      type: string
                    itineraryId:
                      type: string
                      minLength: 1
                    status:
                      type: string
                      enum:
                        - ACTIVE
                        - INACTIVE
                    role:
                      type: string
                      enum:
                        - ADMIN
                        - MENTOR
                        - REGISTERED
                    createdAt:
                      type: string
                      format: date-time
                    updatedAt:
                      type: string
                      format: date-time
                  required:
                    - id
                    - email
                    - dni
                    - itineraryId
                    - status
                    - role
                    - createdAt
                    - updatedAt
        "401":
          description: Invalid token
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: "#/components/schemas/InvalidTokenError"
                  - $ref: "#/components/schemas/MissingTokenError"
        "403":
          description: Forbidden. Acces denied.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ForbiddenError"
                  - example: *a1
        "500":
          description: Other error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Database error
                required:
                  - message
    patch:
      tags:
        - users
      operationId: patchUsersById
      description: Allows a logged in ADMIN user to modify another user.
      summary: Patch a user.
      security:
        - cookieAuth: []
      requestBody:
        required: true
        description: Updates an existing user. The ID is mandatory, and all other fields
          are optional. Provide only the fields that need to be updated.
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                email:
                  type: string
                  format: email
                  example: user@example.cat
                dni:
                  type: string
                password:
                  type: string
                  minLength: 8
                name:
                  type: string
                itineraryId:
                  type: string
                  minLength: 1
                status:
                  type: string
                  enum:
                    - ACTIVE
                    - INACTIVE
                role:
                  type: string
                  enum:
                    - ADMIN
                    - MENTOR
                    - REGISTERED
                specializationId:
                  type: string
              required:
                - id
              additionalProperties: false
      responses:
        "204":
          description: User has been modified
        "400":
          description: Zod validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValidationError"
        "401":
          description: Invalid token
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: "#/components/schemas/InvalidTokenError"
                  - $ref: "#/components/schemas/MissingTokenError"
        "403":
          description: Forbidden. Acces denied.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ForbiddenError"
                  - example: *a1
        "404":
          description: Not found
        "409":
          description: Conflict, data already exists.
        "500":
          description: Other error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Database error
                required:
                  - message
        "502":
          description: Upstream service fail
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UpstreamServiceFail"
  /api/v1/favorites:
    put:
      tags:
        - favorites
      operationId: putFavorites
      description: Allows a logged in users to add/remove favorite resources.
      summary: Put or delete a favorite resource by userId.
      security:
        - cookieAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
              required:
                - id
      responses:
        "204":
          description: Favorite has been added/removed
        "400":
          description: Invalid input
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: "#/components/schemas/ValidationError"
                  - $ref: "#/components/schemas/InputError"
        "401":
          description: Invalid token
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: "#/components/schemas/InvalidTokenError"
                  - $ref: "#/components/schemas/MissingTokenError"
        "404":
          description: User not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MissingUserError"
  /api/v1/itinerary:
    get:
      tags:
        - itinerary
      operationId: listItineraries
      description: Fetches all available itineraries
      summary: Get all itineraries
      responses:
        "200":
          description: List of all itineraries
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                    name:
                      type: string
                      example: Frontend Angular
                    slug:
                      type: string
                      example: frontend-angular
                  required:
                    - id
                    - name
                    - slug
        "503":
          description: The SSO server is not available.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ServiceUnavailableError"
                  - example: *a3