swagger.json

{
  "swagger": "2.0",
  "info": {
    "version": "1.0.0",
    "title": "Barefoot Normads",
    "description": "Barefoot Normads done by Champs in Stackup 3.",
    "contact": {}
  },
  "host": "champs-bn-api.herokuapp.com",
  "basePath": "/api/v1",
  "securityDefinitions": {},
  "schemes": [
    "http",
    "https"
  ],
  "consumes": [
    "application/json"
  ],
  "produces": [
    "application/json"
  ],

  "paths": {
    "/auth/signin": {
      "post": {
        "description": "",
        "summary": "User Sign in",
        "tags": [
          "Auth"
        ],
        "operationId": "signIn",
        "deprecated": false,
        "produces": [
          "application/json"
        ],
        "parameters": [{
          "in": "body",
          "name": "body",
          "description": "signin into user account: Correct user credentials needed to be used for login",
          "required": true,
          "schema": {
            "$ref": "#/definitions/signin"
          }
        }],
        "responses": {
          "200": {
            "description": "User signed in successfully"
          },
          "400": {
            "description": "Incorrect email or password"
          },
          "404": {
            "description": "User does not exist!"
          }
        }
      }
    },
    "/auth/signup": {
      "post": {
        "description": "",
        "summary": "User Sign up",
        "tags": [
          "Auth"
        ],
        "operationId": "signUp",
        "deprecated": false,
        "produces": [
          "application/json"
        ],

        "parameters": [{
          "in": "body",
          "name": "body",
          "description": "Create user account: User credentials needed to be used for signup",
          "required": true,
          "schema": {
            "$ref": "#/definitions/Signup"
          }
        }],
        "responses": {
          "201": {
            "description": "user created, verification email was sent"
          },
          "422": {
            "description": "parameter required or invalid input"
          },
          "500": {
            "description": "verification email wasn't sent"
          }
        }
      }
    },
    "/auth/reset-link": {
      "post": {
        "summary": "Send Email to reset password",
        "description": "User can get an email to reset password, endpoint",
        "tags": [
          "Auth"
        ],
        "operationId": "resetPassword",
        "deprecated": false,
        "produces": [
          "application/json"
        ],
        "parameters": [

          {
            "name": "body",
            "in": "body",
            "required": true,
            "description": "Email which will receve the reset password link",
            "schema": {
              "$ref": "#/definitions/resetEmail"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The email has been sent successfully."
          },
          "400": {
            "description": "Email must be valid"
          },
          "404": {
            "description": "Sorry! This email does not exist in Barefoot system."
          }
        }
      }
    },
    "/auth/update-password/{email}/{token}": {
      "post": {
        "summary": "Update password",
        "description": "User can update password, endpoint",
        "tags": [
          "Auth"
        ],
        "operationId": "updatePassword",
        "deprecated": false,
        "produces": [
          "application/json"
        ],
        "parameters": [

          {
            "name": "email",
            "in": "path",
            "required": true,
            "type": "string",
            "description": "Email"
          },
          {
            "name": "token",
            "in": "path",
            "required": true,
            "type": "string",
            "description": "token to reset password"
          },
          {
            "in": "body",
            "name": "body",
            "description": "password",
            "required": true,
            "schema": {
              "$ref": "#/definitions/updatePassword"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The password has been updated successfully."
          },
          "400": {
            "description": "password must be a valid email"
          },
          "401": {
            "description": "Sorry, the Token is invalid"
          },
          "404": {
            "description": "Sorry! The user does not exist."
          }
        }
      }
    },
    "/users/{userId}/role": {
      "patch": {
        "description": "A super administrator can assign roles to users by using their userId",
        "summary": "Update a User's role",
        "tags": [
          "Users"
        ],
        "operationId": "UpdateRole",
        "deprecated": false,
        "produces": [
          "application/json"
        ],
        "parameters": [{
            "name": "token",
            "in": "header",
            "required": true,
            "type": "string",
            "description": "token identify that a user has signed in"
          },
          {
            "in": "path",
            "name": "userId",
            "type": "string",
            "required": true,
            "description": "userId of a user whose role is about to be updated"
          },
          {
            "name": "Body",
            "in": "body",
            "required": true,
            "description": "Super administrator is able to change roles of a particular user",
            "schema": {
              "$ref": "#/definitions/roleUpdate"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "role is updated successfuly",
            "headers": {}
          },
          "400": {
            "description": "token is malformed/invalid or role field is not valid",
            "headers": {}
          },
          "401": {
            "description": "the requester is not logged in, doesn't have an account or doesn't have Super Administrator privileges",
            "headers": {}
          },
          "404": {
            "description": "user with the provided id doesn't exist",
            "headers": {}
          }
        }
      }
    },
    "/users/?page={page}&limit={limit}": {
      "get": {
        "tags": [
          "Users"
        ],
        "summary": "Viewing all users",
        "description": "super admin can view all user",
        "parameters": [{
            "name": "token",
            "in": "header",
            "required": true,
            "type": "string",
            "description": "token identify that a user has signed in"
          },
          {
            "in": "query",
            "name": "page",
            "type": "integer",
            "required": false,
            "default": 1,
            "description": "parsing a page number"
          },
          {
            "in": "query",
            "name": "limit",
            "type": "integer",
            "required": false,
            "default": 10,
            "description": "parsing a limits of data per page"
          }
        ],
        "responses": {
          "200": {
            "description": "users successfuly retrieved"
          },
          "400": {
            "description": "Malformed/ Incorrect security token ! Check token and try again."
          },
          "401": {
            "description": "User not recognised. Please create account and try again./ Already logged out. Sign in and try again."
          }
        }
      }
    },
    "/users/{userId}": {
      "get": {
        "description": "super admin can view a specific user",
        "summary": "View One user",
        "tags": [
          "Users"
        ],
        "operationId": "ViewOneuser",
        "deprecated": false,
        "produces": [
          "application/json"
        ],
        "parameters": [{
            "name": "token",
            "in": "header",
            "required": true,
            "type": "string",
            "description": "security token"
          },
          {
            "in": "path",
            "name": "userId",
            "type": "integer",
            "required": true,
            "description": "parsing an user Id"
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {}
          },
          "404": {
            "description": "This users doesn't exist in the database",
            "headers": {}
          }
        }
      }
    },
    "/user/{username}/profile": {
      "patch": {
        "description": "",
        "summary": "user update",
        "tags": [
          "Users"
        ],
        "operationId": "update",
        "deprecated": false,
        "produces": [
          "application/json"
        ],
        "consumes": [
          "application/json"
        ],
        "parameters": [{
            "name": "token",
            "in": "header",
            "required": true,
            "type": "string"
          },
          {
            "name": "username",
            "in": "path",
            "required": true,
            "type": "string"
          },
          {
            "in": "body",
            "name": "body",
            "description": "Data needed to update user profile",
            "required": true,
            "schema": {
              "$ref": "#/definitions/profileUpdate"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "user were successfully updated"
          },
          "400": {
            "description": "you can't retrieve or edit other's profile"
          },
          "401": {
            "description": "authentixation failed"
          },
          "422": {
            "description": "parameter required or invalid input"
          }
        }
      },
      "get": {
        "description": "",
        "summary": "user profile",
        "tags": [
          "Users"
        ],
        "operationId": "Retrieve",
        "deprecated": false,
        "produces": [
          "application/json"
        ],
        "consumes": [
           "application/json"
        ],
        "parameters": [
          {
            "name": "token",
            "in": "header",
            "required": true,
            "type": "string"
          },
          {
            "name": "username",
            "in": "path",
            "required": true,
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "User succesfully retrieved."
          },
          "400": {
            "description": "you can't retrieve or edit other's profile"
          },
          "401": {
            "description": "authentication failed"
          },
          "404": {
            "description": "Sorry! The user does not exist."
          }
        }
      }
    },
    "/places": {
      "post": {
        "tags": [
          "Places"
        ],
        "summary": "Places creation",
        "description": "Super administrator can create a place.",
        "parameters": [{
            "name": "token",
            "in": "header",
            "required": true,
            "type": "string",
            "description": "Token identify that a user has signed in"
          },
          {
            "in": "body",
            "name": "body",
            "description": "Data needed to create a place",
            "required": true,
            "schema": {
              "$ref": "#/definitions/PlaceCreation"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Place was created successfully."
          },
          "422": {
            "description": "bad data"
          },
          "409": {
            "description": "This place already exists, use diferent name."
          }
        }
      }
    },
    "/places/?page={page}&limit={limit}": {
      "get": {
        "tags": [
          "Places"
        ],
        "summary": "Viewing all Places",
        "description": "a user should be able to view  all places",
        "parameters": [{
            "name": "token",
            "in": "header",
            "required": true,
            "type": "string",
            "description": "token to authenticate user to the resources"
          },
          {
            "in": "query",
            "name": "page",
            "type": "integer",
            "required": false,
            "default": 1,
            "description": "parsing a page number"
          },
          {
            "in": "query",
            "name": "limit",
            "type": "integer",
            "required": false,
            "default": 10,
            "description": "parsing a limits of data per page"
          }
        ],
        "responses": {
          "200": {
            "description": "places successfuly retrieved"
          },
          "400": {
            "description": "Malformed/ Incorrect security token ! Check token and try again."
          },
          "401": {
            "description": "User not recognised. Please create account and try again./ Already logged out. Sign in and try again."
          }
        }
      }
    },
    "/places/{placeId}": {
      "get": {
        "description": "User can get a specific place",
        "summary": "View One place",
        "tags": [
          "Places"
        ],
        "operationId": "ViewOneplace",
        "deprecated": false,
        "produces": [
          "application/json"
        ],
        "parameters": [{
            "name": "token",
            "in": "header",
            "required": true,
            "type": "string",
            "description": "security token"
          },
          {
            "in": "path",
            "name": "placeId",
            "type": "integer",
            "required": true,
            "description": "parsing an place Id"
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {}
          },
          "404": {
            "description": "This places doesn't exist in the database",
            "headers": {}
          }
        }
      }
    },
    "/trips": {
      "post": {
        "tags": [
          "Trips"
        ],
        "summary": "Trip creation",
        "description": "User can create a trip (One Way Trip, Return Trip and choose Multiple City on a trip)",
        "parameters": [{
            "name": "token",
            "in": "header",
            "required": true,
            "type": "string",
            "description": "token identify that a user has signed in"
          },
          {
            "in": "body",
            "name": "body",
            "description": "data needed to create a trip",
            "required": true,
            "schema": {
              "$ref": "#/definitions/TripCreation"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Trip was created successfully."
          },
          "422": {
            "description": "bad data"
          },
          "409": {
            "description": "This trip already exists, use another reasons or date."
          }
        }
      }
    },
    "/trips/?page={page}&limit={limit}": {
      "get": {
        "tags": [
          "Trips"
        ],
        "summary": "Viewing all trips",
        "description": "a Requester user views all trip requests they've created, a Manager user views all trip requests",
        "parameters": [{
            "name": "token",
            "in": "header",
            "required": true,
            "type": "string",
            "description": "token identify that a user has signed in"
          },
          {
            "in": "query",
            "name": "page",
            "type": "integer",
            "required": false,
            "default": 1,
            "description": "parsing a page number"
          },
          {
            "in": "query",
            "name": "limit",
            "type": "integer",
            "required": false,
            "default": 10,
            "description": "parsing a limits of data per page"
          }
        ],
        "responses": {
          "200": {
            "description": "trip requests successfuly retrieved"
          },
          "400": {
            "description": "Malformed/ Incorrect security token ! Check token and try again."
          },
          "401": {
            "description": "User not recognised. Please create account and try again./ Already logged out. Sign in and try again."
          }
        }
      }
    },
    "/trips/{tripId}": {
      "get": {
        "description": "User can get a specific trip",
        "summary": "View One trip",
        "tags": [
          "Trips"
        ],
        "operationId": "retrieveTrip",
        "deprecated": false,
        "produces": [
          "application/json"
        ],
        "parameters": [{
            "name": "token",
            "in": "header",
            "required": true,
            "type": "string",
            "description": "security token"
          },
          {
            "in": "path",
            "name": "tripId",
            "type": "integer",
            "required": true,
            "description": "parsing an trip Id"
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "headers": {}
          },
          "401": {
            "description": "You are not allowed to access this trip",
            "headers": {}
          }
        }
      },
      "patch": {
        "description": "A line manager can respond to assigned trip requests",
        "summary": "accept or reject a trip request",
        "tags": [
          "Trips"
        ],
        "operationId": "RespondTrip",
        "deprecated": false,
        "produces": [
          "application/json"
        ],
        "parameters": [{
            "name": "token",
            "in": "header",
            "required": true,
            "type": "string",
            "description": " token indicating that a manager has signed in"
          },
          {
            "in": "path",
            "name": "tripId",
            "type": "string",
            "required": true,
            "description": "tripId of a trip to be accepted or rejected"
          },
          {
            "name": "Body",
            "in": "body",
            "required": true,
            "description": "status of the trip to be sent",
            "schema": {
              "$ref": "#/definitions/TripRespond"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "trip is successfuly accepted or rejected",
            "headers": {}
          },
          "400": {
            "description": "token is malformed/invalid or status field is not valid",
            "headers": {}
          },
          "401": {
            "description": "the requester is not logged in and not allowed to access the endpoint",
            "headers": {}
          },
          "404": {
            "description": "trip with the provided id doesn't exist, User doesn't have privileges",
            "headers": {}
          }
        }
      }
    },
    "/accommodation": {
      "post": {
        "tags": [
          "Accommodation"
        ],
        "summary": "Accommodation registration",
        "description": "User can register an accommodation",
        "parameters": [{
            "name": "token",
            "in": "header",
            "required": true,
            "type": "string",
            "description": "token given when user signs in"
          },
          {
            "in": "body",
            "name": "body",
            "description": "data needed to register an accommodation",
            "required": true,
            "schema": {
              "$ref": "#/definitions/AccommodationCreation"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Accommodation was registered successfully."
          },
          "422": {
            "description": "Invalid data"
          },
          "409": {
            "description": "Accommodation facility already exists"
          }
        }
      }
    }
    
  },
  "definitions": {
    "signin": {
      "title": "Sign in request",
      "type": "object",
      "example": {
        "email": "chrischris@example.com",
        "password": "123456789"
      },
      "required": [
        "email",
        "password"
      ],
      "properties": {
        "email": {
          "type": "string"
        },
        "password": {
          "type": "string"
        }
      }
    },
    "Signup": {
      "title": "Sign up request",
      "type": "object",
      "example": {
        "firstname": "ama",
        "lastname": "user",
        "username": "amauser",
        "email": "amauser@example.com",
        "password": "123456789"
      },
      "required": [
        "firstname",
        "lastname",
        "username",
        "email",
        "password"
      ],
      "properties": {
        "firstname": {
          "type": "string"
        },
        "lastname": {
          "type": "string"
        },
        "username": {
          "type": "string"
        },
        "email": {
          "type": "string"
        },
        "password": {
          "type": "string"
        }
      }
    },
    "resetEmail": {
      "title": "Reset password request",
      "example": {
        "email": "chrischris@example.com"
      },
      "type": "object",
      "properties": {
        "email": {
          "type": "string"
        }
      },
      "required": [
        "email"
      ]
    },
    "updatePassword": {
      "title": "Password update request",
      "example": {
        "password": "123456789",
        "passwordConfirm": "123456789"
      },
      "type": "object",
      "properties": {
        "password": {
          "type": "password"
        },
        "passwordConfirm": {
          "type": "password"
        }
      },
      "required": [
        "password",
        "passwordConfirm"
      ]
    },
    "roleUpdate": {
      "title": "User role update request",
      "example": {
        "role": "Travel Administrator"
      },
      "type": "object",
      "properties": {
        "role": {
          "type": "string"
        }
      },
      "required": [
        "role"
      ]
    },
    "profileUpdate": {
      "title": "User profile update request",
      "example": {
        "lastname": "thislastname",
        "firstname": "thisfirstname",
        "username": "johnDoe",
        "gender": "Male",
        "birthDate": "2000-04-03",
        "preferredLanguage": "English",
        "preferredCurrency": "RWF",
        "location": "Kigali",
        "department": "IT",
        "emailNotifications": false,
        "inAppNotifications": true
      },
      "type": "object",
      "properties": {
        "lastname": {
          "type": "string"
        },
        "firstname": {
          "type": "string"
        },
        "username": {
          "type": "string"
        },
        "gender": {
          "type": "string"
        },
        "birthDate": {
          "type": "date"
        },
        "preferredLanguage": {
          "type": "string"
        },
        "preferredCurrency": {
          "type": "string"
        },
        "location": {
          "type": "string"
        },
        "department": {
          "type": "string"
        },
        "emailNotifications": {
          "type": "boolean"
        },
        "inAppNotifications": {
          "type": "boolean"
        }
      }
    },
    "PlaceCreation": {
      "title": "create a place request",
      "example": {
        "name": "butare branch",
        "country": "Rwanda",
        "city": "Butare"
      },
      "type": "object",
      "required": [
        "name",
        "country",
        "city"
      ],
      "properties": {
        "name": {
          "type": "string"
        },
        "country": {
          "type": "string"
        },
        "city": {
          "type": "string"
        }
      }
    },
    "TripCreation": {
      "title": "create a trip request",
      "example": {
        "departure": 1,
        "destination": 2,
        "date": "2050-09-13",
        "returnDate": "2050-10-30",
        "reasons": "hound issues"
      },
      "type": "object",
      "required": [
        "departure",
        "destination",
        "date",
        "reasons"
      ],
      "properties": {
        "departure": {
          "type": "integer"
        },
        "destination": {
          "type": "integer"
        },
        "date": {
          "type": "date"
        },
        "reasons": {
          "type": "string"
        },
        "returnDate": {
          "type": "date"
        }
      }
    },
    "TripRespond": {
      "title": "trip respond request",
      "example": {
        "status": "accepted"
      },
      "type": "object",
      "properties": {
        "status": {
          "type": "string"
        }
      },
      "required": [
        "status"
      ]
    },
    "AccommodationCreation": {
      "title": "register an accommodation",
      "example": {
        "name": "Mille Collines Hotel",
          "description": "we can have you any time",
          "locationId": 1,
          "amenities": "hey hey You will enjoy",
          "images":["https://mcdn.wallpapersafari.com/medium/91/83/jECzOG.jpg", "https://mcdn.wallpapersafari.com/medium/40/15/fmFJbU.jpg"],
          "rooms": [{
            "roomType": "Single",
            "numberOfRooms": 5,
            "roomAmenities": "hey hey You will enjoy",
            "roomImages":["https://mcdn.wallpapersafari.com/medium/91/83/jECzOG.jpg", "https://mcdn.wallpapersafari.com/medium/40/15/fmFJbU.jpg"],
            "cost": 600
          },
          {
            "roomType": "Double",
            "numberOfRooms": 5,
            "roomAmenities": "hey hey You will enjoy",
            "roomImages":["https://mcdn.wallpapersafari.com/medium/91/83/jECzOG.jpg", "https://mcdn.wallpapersafari.com/medium/40/15/fmFJbU.jpg"],
            "cost": 600
          }]
      },
      "type": "object",
      "required": [
        "name",
        "description",
        "locationId",
        "amenities",
        "rooms"
      ],
      "properties": {
        "departure": {
          "type": "string"
        },
        "description": {
          "type": "string"
        },
        "locationId": {
          "type": "integer"
        },
        "amenities": {
          "type": "string"
        },
        "rooms": {
          "type": "array"
        }
      }
    }
  }
}