employee.yaml

---
swagger: '2.0' #version of Swagger
info: # High Level information of API
  description: Sample Swagger Demo #Give the description of API
  version: 1.0.0 #API version
  title: Swagger Employee Demo # API title
  license: #Swagger license info
    name: Apache 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
host: localhost # Host Name
basePath: /v1 #Basepath when there are multiple versions of API running
tags: # Tag information for each API operation. Multiple tags for multiple API operation
  - name: employee #Tag name
    description: Everything about your Employee #Tag description of API operation
  - name: health
    description: Readiness probe
schemes:
  - http #security schemes
paths:
  '/employees':
    post:
      tags:
      - employee
      summary: Add a new employee
      description: Add a new employees
      operationId: addEmployeeDetails
      parameters:
      - in: body
        name: body
        description: Employees object that needs to be added 
        required: true
        schema:
          $ref: '#/definitions/Employee'
      responses:
        405:
          description: Invalid input
  '/employees/{employeeId}': #Request Mapping path of REST API
    get: #Request method type, GET,POST etc.
      tags: # Refer to created tag above
        - employee
      summary: Find employee by ID #Summary
      description: Returns a single Employee #Description of API operation
      operationId: getEmployeeDetails #Method name
      produces:
        - application/json #Response content type
      parameters:
        - name: employeeId #Input parameter
          in: path #path variable
          description: ID of Employee to return #description of parameter
          required: true #Is mandatory
          type: integer #data type
          format: int64 #data type format, signed 64 bits
      responses: # API response
        '200': #Successful status code
          description: successful operation #Successful status description
          schema:
            $ref: '#/definitions/Employee' #Response object details
        '400': #Unsuccessful response code
          description: Invalid Employee ID supplied #Unsuccessful response description
        '404': #Unsuccessful response code
          description: Employee not found #Unsuccessful response description
    put: #Request method type, GET,POST etc.
      tags: # Refer to created tag above
        - employee
      summary: Update employee by ID #Summary
      description: Returns a single Employee #Description of API operation
      operationId: updateEmployeeDetails #Method name
      produces:
        - application/json #Response content type
      parameters:
        - name: employeeId
          in: path
          description: name that need to be updated
          required: true
          type: string
        - in: body
          name: body
          description: Updated user object
          required: true
          schema:
            $ref: '#/definitions/Employee'
      responses: # API response
        '400': #Unsuccessful response code
          description: Invalid Employee ID #Unsuccessful response description
        '404': #Unsuccessful response code
          description: Employee not found #Unsuccessful response description
    delete: #Request method type, GET,POST etc.
      tags: # Refer to created tag above
        - employee
      summary: Deletes employee by ID #Summary
      description: Returns a single Employee #Description of API operation
      operationId: deleteEmployeeDetails #Method name
      produces:
        - application/json #Response content type
      parameters:
        - name: employeeId #Input parameter
          in: path #path variable
          description: ID of Employee that needs to be updated #description of parameter
          required: true #Is mandatory
          type: integer #data type
          format: int64 #data type format, signed 64 bits
      responses: # API response
        400:
          description: Invalid ID employee
        404:
          description: employee not found
  '/health':
    get:
      tags:
        - health
      operationId: getHealth
      produces:
        - application/json
      responses:
        '200': #Successfule status code
           description: successful operation #Successful status description
definitions: # Object definition
  Employee: #Employee Object
    type: object
    properties: #Object properties
      id: #Id attribute
        type: integer
        format: int64
      firstName: #Firstname attribute
        type: string
        description: Employee First Name #data type description
      lastName: #Lastname attribute
        type: string #Data type
        description: Employee Last Name #Data type description
    xml:
      name: employee #xml root element when returning xml