hr-employees.yaml

openapi: 3.0.0
info:
  version: '1.0.0'
  title: 'HR API'
  description: 'An API to allow user to obtain existing information about employees.'
  termsOfService: https://ortizol.co/tos
  contact:
    name: John
    url: ortizol.co
    email: johnortizo@outlook.com
  license:
    name: BSD
    url: license.bsd.org

servers:
  - url: http://localhost:8080
    description: Devevelopment server
  - url: http://ortizol.co:4748
    description: Production server

paths:
  /employees:
    get:
      description: Obtain information about employees from the HR DB.
      parameters:
        - name: bodyLimit
          in: query
          description: The amount of employees returned
          schema:
            type: integer
            minimum: 1
            maximum: 5
            example: 2
        - name: pageLimit
          in: query
          description: The pages to return employees info
          schema:
            type: integer
            minimum: 1
            maximum: 5
            example: 2
      responses:
        200:
          description: Successful pull of employee info
          content:
            application/json:
              schema:
                type: array
                items:
                $ref: '#/components/schemas/Employee'
        404:
          description: Server not found
    post:
      description: Create a new employee in the DB.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              $ref: '#/components/schemas/Employee'
          application/xml:
            schema:
              type: object
              $ref: '#/components/schemas/Employee'
      responses:
        200:
           description: Successfully created a new employee.
  /employees/{id}:
    get:
      description: Obtain information about specific employee
      parameters:
        - in: path
          name: id
          required: true
          description: The ID of the employee
          schema:
            type: integer
            example: 13
      responses:
        200:
          description: Sucesss
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/Employee'
            application/xml:
              schema:
                type: object
                $ref: '#/components/schemas/Employee'
components:
  schemas:
    Employees:
      description: Array of employee info
      type: array
      items:
        $ref: '#/components/schemas/Employee'
    Employee:
      description: Model containing employee info
      properties:
        id:
          type: integer
          example: 4
        employee_name:
          type: string
          example: John Ortiz
        employee_title:
          type: string
          example: Developer