openapi.yaml

openapi: 3.0.0

info:
  title: docs-drive.it API
  description: Simple APIs for user authentication and management for the docs-drive.it personal area
  contact:
    name: API support
    url: https://github.com/Giuliopime/docs-drive-backend/issues
  license:
    name: MIT
    url: https://choosealicense.com/licenses/mit/
  version: 1.0.0

servers:
  - url: https://api.docs-drive.it/{version}
    variables:
      version:
        default: v1
  - url: http://localhost:12000/{version}
    description: Just for testing purpouses.
    variables:
      version:
        default: v1


security:
  - cookieAuth: []

paths:
  /login:
    post:
      summary: Used to login.
      description: Receives login in credentials and sends back a session cookie.
      security: []
      requestBody:
        required: true
        description: JSON containing email and password of the user.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserLoginData'
      responses:
        "200":
          description: OK
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /user:
    get:
      summary: Gets the logged in user.
      description: Gets a single user matching the email and password provided via authentication.
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /changePassword:
    post:
      summary: Changes your password.
      description: Allows the logged in user to change its password.
      requestBody:
        required: true
        description: JSON containing old and new password of the user.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewPasswordInfo'
      responses:
        "200":
          description: OK
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /logout:
    get:
      summary: Logs out the current logged in user.
      description: Terminates the session of the user resulting in a logout.
      responses:
        "200":
          description: OK
        "401":
          $ref: "#/components/responses/Unauthorized"
  /files/{id}:
    get:
      summary: Gets a file.
      description: Gets a specific file of the current logged in user.
      parameters:
        - $ref: "#/components/parameters/idParam"
      responses:
        "200":
          description: OK
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"


  /admin/users:
    get:
      summary: Get all the users.
      description: Retrieves the full list of users.
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/User"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"

  /admin/user/{email}:
    get:
      summary: Get a single user.
      description: Gets a single user matching the provided email parameter.
      parameters:
        - $ref: "#/components/parameters/emailParam"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
    post:
      summary: Modify a single user.
      description: Modify a user matching the provided email parameter.
      parameters:
        - $ref: "#/components/parameters/emailParam"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/User"
      responses:
        "200":
          description: OK
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
    put:
      summary: Create a new user.
      description: Creates a new user (needs to match the provided email parameter).
      parameters:
        - $ref: "#/components/parameters/emailParam"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/User"
      responses:
        "200":
          description: OK
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "405":
          $ref: "#/components/responses/NotAllowed"
    delete:
      summary: Delete a user.
      description: Deletes a user matching the provided email parameter.
      parameters:
        - $ref: "#/components/parameters/emailParam"
      responses:
        "200":
          description: OK
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"

  /admin/user/{email}/files/{id}:
    get:
      summary: Gets a single file.
      description: Gets a single file of the user matching the provided email parameter.
      parameters:
        - $ref: "#/components/parameters/emailParam"
        - $ref: "#/components/parameters/idParam"
      responses:
        "200":
          description: OK
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
    post:
      summary: Modify a file name.
      description: Modify a file name of the user matching the provided email parameter.
      parameters:
        - $ref: "#/components/parameters/emailParam"
        - $ref: "#/components/parameters/idParam"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NewFileInfo"
      responses:
        "200":
          description: OK
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
    delete:
      summary: Deletes a file.
      description: Deletes a file of a user matching the provided email parameter.
      parameters:
        - $ref: "#/components/parameters/emailParam"
        - $ref: "#/components/parameters/idParam"
      responses:
        "200":
          description: OK
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /admin/user/{email}/files:
    put:
      summary: Create a new file.
      description: Creates a new file for a user matching the provided email parameter.
      parameters:
        - $ref: "#/components/parameters/emailParam"
      requestBody:
        content:
          multipart/form-data:
            schema:
              type:  object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        "200":
          description: OK
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"

components:
  securitySchemes:
    cookieAuth:
      type: apiKey
      in: cookie
      name: user_session_id
  responses:
    BadRequest:
      description: Usually happens when a request body is needed and the body is missing some properties, check for example the User schema.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    Unauthorized:
      description: Request wasn't authorized via basic auth
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    Forbidden:
      description: Missing permissions for a certain action, some actions like editing or deleting a user can only be made by a user with admin priviliges.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    NotFound:
      description: The resource isn't present in the server.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    NotAllowed:
      description: The method is not allowed, for example when trying to create a user and a user with the same email already exists.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"

  parameters:
    emailParam:
      description: The email of a user.
      name: email
      in: path
      required: true
    idParam:
      description: id of an entity, like files for example.
      name: id
      in: path
      required: true

  schemas:
    UserLoginData:
      description: Email and password of a user.
      type: object
      properties:
        email:
          type: string
          description: The email of the user
        password:
          type: string
          description:
            The password of the user
      required:
        - email
        - password
    User:
      description: A single user entity.
      type: object
      properties:
        email:
          type: string
          description: The email of the user
        password:
          type: string
          description: The password of the user
        admin:
          type: boolean
          description: Whether the user is an admin of the platform
        name:
          type: string
          description: The legal name of the user
        surname:
          type: string
          description: The legal surname of the user
        id_code:
          type: string
          description: The legal tax ID code ("codice fiscale" in Italy) of the user
      required:
        - email
        - password
        - admin
        - name
        - surname
        - id_code
    NewPasswordInfo:
      description: Old and new password for password change.
      type: object
      properties:
        old_password:
          type: string
          description: Old password of the user.
        new_password:
          type: string
          description: New password of the user.
      required:
        - old_password
        - new_password
    NewFileInfo:
      description: New informations for an existing file.
      type: object
      properties:
        new_name:
          type: string
          description: New name for the file.
      required:
        - new_name
    Error:
      type: object
      properties:
        code:
          type: string
          description: Response code.
        message:
          type: string
          description: Info about the error
      required:
        - code
        - message