swagger.yaml

openapi: '3.0.2'
info:
  version: '2.0.0'
  title: UniBuk
  description: We need to develop an online service for University book suggestions and content sharing that will allow University students ton get information about  books, notes and resources they can use in their courses, as well as donwload contents shared by other users. We want to deliver a web version of this service and a client application.
  license:
    name: MIT
    url: https://github.com/apiaryio/polls-api/blob/master/LICENSE
  contact:
    name: 'team #10'
    url: 'https://github.com/Pappol/UniBuk'
servers:
  - url: http://localhost:8080/v1/
    description: Localhost
  - url: https://unibuk-backend.herokuapp.com/v1/
    description: Heroku server

paths: 
  
  /users/signup:
    
    post: 
      description: Creates a new user in the database
      requestBody: 
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email: 
                  type: string
                password: 
                  type: string
                username: 
                  type: string
                firstName: 
                  type: string
                lastName: 
                  type: string
      responses:
        '201':
          description: success
          content: 
            application/json:
              schema:
                type: object
                properties:
                  message: 
                    type: string
                    example: User created
        '409':
          description: Mail altrady exists
          content: 
            application/json:
              schema:
                type: object
                properties:
                  message: 
                    type: string
                    example: Mail exists
        '500':
          description: Database error
          content: 
            application/json:
              schema:
                type: object
                properties:
                  error: 
                    type: string
                    example: database error type
        '501':
          description: Password hashing error
          content: 
            application/json:
              schema:
                type: object
                properties:
                  error: 
                    type: string
                    example: Hashing error type
          
  /users/login:
    
    post:
      description: Checks if a user already exists in the database and returns a valid access token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email: 
                  type: string
                  example: mymail@example.com
                password:
                  type: string
                  example: jyclkvadjhvs
              required:
                - email
                - password
      responses:
        '200':
          description: Login success
          content: 
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  token: 
                    type: string
                  id:
                    type: string
                  university:
                    type: string
                required:
                  - code
                  - message
                  - id
                  - university
              example: 
                token: yqw98q48y9w4fyp9gy4hrvpr89hqp484qgfg p9qgf4
                message: Auth Successful
                id: 5fab15fdd9fe8e536c4df414
                university: Università di Trento
        '401':
          description: Generic failure
          content: 
            application/json:
              schema:
                type: object
                properties:
                  message: 
                    type: string
                    example: Auth failed
        '402':
          description: Error in compairing password with hash
          content: 
            application/json:
              schema:
                type: object
                properties:
                  message: 
                    type: string
                    example: Auth failed:failed to compare hash
        '403':
          description: User doesn't exists
          content: 
            application/json:
              schema:
                type: object
                properties:
                  message: 
                    type: string
                    example: Auth failed:no mail found
        '500':
          description: Database error
          content: 
            application/json:
              schema:
                type: object
                properties:
                  error: 
                    type: string
                    example: Database error type
  
  /users/{id}:
  
    get: 
      description: Obtains information about a specific user
      security:
        - jwtAuth: []
      parameters:
        - in: path
          name: id
          required: true
          description: The id of the user
          schema: 
            type: string
            example: mongoose auto generated
      responses:
        '200':
          description: Successful pull of one user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: User with this id doesn't exists 
          content: 
            application/json:
              schema:
                type: object
                properties:
                  message: 
                    type: string
                    example: No valid entry found for provided ID
        '500':
          description: Find failed in the database
          content: 
            application/json:
              schema:
                type: object
                properties:
                  error: 
                    type: string
                    example: Database error type

    patch:
      description: Edits a specific user from the database
      security:
        - jwtAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items: 
                type: object
                properties:
                  propName:
                    type: string
                    example: username
                  value:
                    type: object #could be other than object (object is the most generic allowed)
                    example: salt bae
      parameters:
        - in: path
          name: id
          required: true
          description: The id of the user
          schema:
            type: string
            example: mongoose auto generated
      responses:
        '200':
          description: User update
          content: 
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example: 
                message: User updated
        '500':
          description: Update failed in the database
          content: 
            application/json:
              schema:
                type: object
                properties:
                  error: 
                    type: string
                    example: Database error type

    delete:
      description: Deletes a specific user from the database
      security:
        - jwtAuth: []
      parameters:
        - in: path
          name: id
          required: true
          description: The id of the user
          schema: 
            type: string
            example: mongoose auto generated
      responses:
        '200':
          description: User delete
          content: 
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example: 
                message: User deleted
        '500':
          description: Update failed in the database
          content: 
            application/json:
              schema:
                type: object
                properties:
                  error: 
                    type: string
                    example: Database error type

  /users/{id}/contents:
    get: 
      description: Obtains all contents related to a user
      parameters:
        - in: path
          name: id
          required: true
          description: The id of the user
          schema: 
            type: string
            example: mongoose auto generated
      responses:
        '200':
          description: An array with related contents
          content:
            application/json:
              schema:
                type: object
                properties:
                  count: 
                    type: number
                    example: 1
                  books: 
                    type: array
                    items:
                      $ref: '#/components/schemas/Content'
        '500':
          description: Find failed in database
          content: 
            application/json:
              schema:
                type: object
                properties:
                  error: 
                    type: string
                    example: Database error type

  /users/{id}/follow:
    patch:
      description: Adds something to a specific user in the database
      security:
        - jwtAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items: 
                type: object
                properties:
                  propName:
                    type: string
                    example: follow
                  value:
                    type: object #could be other than object (object is the most generic allowed)
                    example: mongoose auto generated
      parameters:
        - in: path
          name: id
          required: true
          description: The id of the user
          schema:
            type: string
            example: mongoose auto generated
      responses:
        '200':
          description: User update
          content: 
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example: 
                message: User updated
        '500':
          description: Update failed in the database
          content: 
            application/json:
              schema:
                type: object
                properties:
                  error: 
                    type: string
                    example: Database error type
  
  /books:
  
    get:
      description: Obtains the information of all the books in database
      responses: 
        '200':
          description: Successful pull of all the books
          content:
            application/json:
              schema:
                type: object
                properties:
                  count: 
                    type: number
                    example: 1
                  books: 
                    type: array
                    items:
                      $ref: '#/components/schemas/Book'
        '500':
          description: Find failed in the database
          content: 
            application/json:
              schema:
                type: object
                properties:
                  error: 
                    type: string
                    example: Database error type
  
  /books/{id}:
  
    get: 
      description: Obtains information about a specific book
      parameters:
        - in: path
          name: id
          required: true
          description: The id of the book
          schema:
            type: string
            example: mongose auto generated
      responses:
        '200':
          description: Successful pull of one book
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Book'
        '404':
          description: Book with this id doesn't exists 
          content: 
            application/json:
              schema:
                type: object
                properties:
                  message: 
                    type: string
                    example: No valid entry found for provided ID
        '500':
          description: Find failed in the database
          content: 
            application/json:
              schema:
                type: object
                properties:
                  error: 
                    type: string
                    example: Database error type

  /books/{id}/review:
  
    patch:
      description: Updates a book information; useful for adding a new comment/review to a book with provided {id}
      security:
        - jwtAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items: 
                type: object
                properties:
                  propName:
                    type: string
                    example: comments
                  value:
                    type: object #could be other than object (object is the most generic allowed)
                    example: Sample review
      parameters:
        - in: path
          name: id
          required: true
          description: The id of the book
          schema:
            type: string
            example: mongoose auto generated
      responses:
        '200':
          description: The book has been successfully updated
          content: 
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example: 
                message: Book updated
        '500':
          description: Update failed in the database
          content: 
            application/json:
              schema:
                type: object
                properties:
                  error: 
                    type: string
                    example: Database error type
                    
  /books/{bId}/questions/{qId}:
    patch:
      description: Adds an answer to a question {id} for a book with provided {id}
      security:
        - jwtAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                text: 
                  type: string
                  example: Tranquillo, è molto buono
      parameters:
        - in: path
          name: bId
          required: true
          description: The id of the book
          schema:
            type: string
            example: mongoose auto generated
        - in: path
          name: qId
          required: true
          description: The id of the question
          schema:
            type: string
            example: mongoose auto generated
      responses:
        '200':
          description: Review has been successfully added
          content: 
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example: 
                message: Added answer
        '500':
          description: Update failed in the database
          content: 
            application/json:
              schema:
                type: object
                properties:
                  error: 
                    type: string
                    example: Database error type
  
  /contents:
  
    get:
      description: Obtains the information of the contents in database
      parameters:
        - in: query
          name: university
          description: Filter by university
          schema: 
            type: string
            example: Università di Trento
      responses:
        '200':
          description: Successful pull of one book
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Content'
        '500':
          description: Find failed in the database
          content: 
            application/json:
              schema:
                type: object
                properties:
                  error: 
                    type: string
                    example: Database error type

    post: 
      description: Creates a new content in the database
      requestBody: 
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                creator: 
                  type: string
                  example: mongoose auto generated
                date: 
                  type: number
                  example: 2020
                name: 
                  type: string
                  example: MyNewCoolContent
                url: 
                  type: string
                  example: myWebsite.com/MyNewCoolContent
                dscription: 
                  type: string
                  example: This is my new cool content
                image:
                  type: string
                  example: myWebsite.com/MyNewCoolContent/image
      responses:
        '201':
          description: POST Success
          content: 
            application/json:
              schema:
                type: object
                properties:
                  message: 
                    type: string
                    example: Content created
        '409':
          description: Mail altrady exists
          content: 
            application/json:
              schema:
                type: object
                properties:
                  message: 
                    type: string
                    example: Content with that name already exists
        '500':
          description: Database error
          content: 
            application/json:
              schema:
                type: object
                properties:
                  error: 
                    type: string
                    example: Database error type
  
  /contents/{id}:
    
    get:
      description: Obtains information about a specific content
      parameters:
        - in: path
          name: id
          required: true
          description: The id of the book
          schema:
            type: string
            example: mongose auto generated
      responses:
        '200':
          description: Successful pull of one content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Content'
        '404':
          description: Content with this id doesn't exists 
          content: 
            application/json:
              schema:
                type: object
                properties:
                  message: 
                    type: string
                    example: No valid entry found for provided ID
        '500':
          description: Find failed in the database
          content: 
            application/json:
              schema:
                type: object
                properties:
                  error: 
                    type: string
                    example: Database error type
    patch:
      description: Edits a specific content from the database
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items: 
                type: object
                properties:
                  propName:
                    type: string
                    example: name
                  value:
                    type: object #could be other than object (object is the most generic allowed)
                    example: The best paper in the world
      parameters:
        - in: path
          name: id
          required: true
          description: The id of the content
          schema:
            type: string
            example: mongoose auto generated
      responses:
        '200':
          description: Content update
          content: 
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example: 
                message: Content updated
        '500':
          description: Update failed in the database
          content: 
            application/json:
              schema:
                type: object
                properties:
                  error: 
                    type: string
                    example: Database error type
    
                    
  /contents/{id}/review:
    patch:
      description: Updates a content information; useful for adding a new comment/review to a content with provided {id}
      security:
        - jwtAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items: 
                type: object
                properties:
                  propName:
                    type: string
                    example: comments
                  value:
                    type: object #could be other than object (object is the most generic allowed)
                    example: Sample review
      parameters:
        - in: path
          name: id
          required: true
          description: The id of the content
          schema:
            type: string
            example: mongoose auto generated
      responses:
        '200':
          description: Content has been successfully updated
          content: 
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example: 
                message: Content updated
        '500':
          description: Update failed in the database
          content: 
            application/json:
              schema:
                type: object
                properties:
                  error: 
                    type: string
                    example: Database error type

  /contents/{id}/view:
    post:
      description: Increments by 1 the views of a given content
      parameters:
        - in: path
          name: id
          required: true
          description: The id of the content
          schema:
            type: string
            example: mongoose auto generated
      responses:
        '200':
          description: View counter has been successfully updated
          content: 
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example: 
                message: Views counter has been incremented
        '500':
          description: Error in updating counter
          content: 
            application/json:
              schema:
                type: object
                properties:
                  error: 
                    type: string
                    example: database error type
       
  /contents/{cId}/questions/{qId}:
    patch:
      description: Adds an answer to a question {id} for a content with provided {id}
      security:
        - jwtAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                text: 
                  type: string
                  example: Tranquillo, è molto buono
      parameters:
        - in: path
          name: cId
          required: true
          description: The id of the content
          schema:
            type: string
            example: mongoose auto generated
        - in: path
          name: qId
          required: true
          description: The id of the question
          schema:
            type: string
            example: mongoose auto generated
      responses:
        '200':
          description: Review has been successfully added
          content: 
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example: 
                message: Added answer
        '500':
          description: Update failed in the database
          content: 
            application/json:
              schema:
                type: object
                properties:
                  error: 
                    type: string
                    example: Database error type
  /search:
  
    get:
      description: Filter by name books, contents and users
      parameters:
        - in: path
          name: query
          required: true
          description: Any field of content, book or user except for password and objects keys
          schema:
            type: string
            example: myBook
      responses:
        '200':
          description: Successful pull of one content
          content:
            application/json:
              schema:
                type: object
                properties:
                  books:
                    type: array
                    items:
                      $ref: '#/components/schemas/Book'
                  contents:
                    type: array
                    items:
                      $ref: '#/components/schemas/Content'
                  users:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
        '500':
          description: Search failed in the database
          content: 
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Database error type
components:

  securitySchemes:
    jwtAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    User:
      description: Model containing user info
      type: object
      properties:
        _id: 
          type: string
          example: mongoose auto generated
        email:
          type: string
          example: myemail@example.com
        username:
          type: string
          example: th3h4ck3r
        firstName:
          type: string
          example: Mario
        lastName:
          type: string
          example: Rossi
        password:
          type: string
          example: lihv9wflnns
        studentCreeds:
          type: object
          properties:
            university: 
              type: string
              example: University of Trento
            course:
              type: string
              example: Software Engineering II
            year: 
              type: number
              example: 3
        verified:
          type: boolean
          example: true
        contents:
          type: array
          items:
            $ref: '#/components/schemas/Content'
        favourites:
          type: array
          items:
            type: object
            properties:
              content:
                $ref: '#/components/schemas/Content'
              book:
                $ref: '#/components/schemas/Book'
        Links:
          type: object
          properties:
            website: 
              type: string
              example: www.mywebsite.com
              default: ""
            contactEmail:
              type: string
              example: myemail@gmail.com
              default: ""
            linkedin:
              type: string
              example: www.linkedin.com/mypage
              default: ""
            gitHub:
              type: string
              example: www.github.com/mypage
              default: ""
        profileImage:
          type: string
          example: https://thispersondoesnotexist.com/image
        follow:
          type: array
          items:
            $ref: '#/components/schemas/User'
            example: mongoose auto generated

      required:
        - _id
        - email
        - username
        - firstName
        - lastName
        - password
    
    Book:
      description: Model containing book info
      type: object
      properties:
        _id: 
          type: string
          example: mongoose auto generated
        isbn:
          type: string
          example: '80000635513238000034'
        title:
          type: string
          example: Dragon Book
        author:
          type: string
          example: Gigi
        year:
          type: number
          example: 1987
        editor:
          type: string
          example: Mondadori
        description:
          type: string
          example: The almighty book of LFC
        image:
          type: string
          example: /uploads/books/photo.jpg
        validFor:
          type: array
          items:
            type: object
            properties:
              university:
                type: string
                example: University of Trento
              course:
                type: string
                example: LFC
        contents:
          type: array
          items:
            $ref: '#/components/schemas/Content'
        tags:
          type: array
          items:
            type: string
            example: LFC
        comments:
          type: array
          items:
            type: object
            properties:
              rank: 
                type: number
                example: 4
              text: 
                type: string
                example: Wow! So useful!
              author:
                $ref: '#/components/schemas/User'
        questions:
          type: array
          items: 
            type: object
            properties:
              quest:
                type: string
                example: Are the authors nice people?
              answers:
                type: array
                items:
                  type: string
                  example: I know them, they are
      required:
        - _id
        - isbn
        - title
        - author
        - year
        - editor
        - description
        - image
    
    Content:
      description: Model containing a content info (paper, software... but NOT a book)
      type: object
      properties:
        _id:
          type: string
          example: mongoose auto generated
        creator:
          $ref: '#/components/schemas/User'
        co_creators:
            type: array
            items:
              $ref: '#/components/schemas/User'
        date:
          type: number
          example: 2020
        name:
          type: string
          example: Dispensa Calcolatori
        url:
          type: string
          example: https://github.com/filippodaniotti/Appunti-LFC
        description:
          type: string
          example: How to beat Calcolatori @UniTN
        image:
          type: string
          example: imgurl.com/contentphoto
        views:
          type: number
          example: 313
          default: 0
        validFor:
          type: array
          items:
            type: object
            properties:
              university:
                type: string
                example: University of Trento
              course:
                type: string
                example: LFC
        books:
          type: array
          items:
            $ref: '#/components/schemas/Book'
        tags: 
          type: array
          items:
            type: string
            example: Calcolatori
        comments:
          type: array
          items:
            type: object
            properties:
              rank: 
                type: number
                example: 4
              text: 
                type: string
                example: Wow! So useful!!
              author:
                $ref: '#/components/schemas/User' 
        questions:
          type: array
          items: 
            type: object
            properties:
              quest:
                type: string
                example: Are the authors nice people?
              answers:
                type: array
                items:
                  type: string
                  example: I know them, they are
      required:
        - _id
        - creator
        - date
        - name
        - url
        - description
        - image