employes_v3.yaml

openapi: 3.0.1
info:
  title: Employees API
  description: This is a preliminary definition to Employees system API
  version: 1.0.0
servers:
- url: https://employees.swagger.io/v2
- url: http://employees.swagger.io/v2
tags:
- name: employees
  description: Employees API
paths:
  /employees:
    get:
      tags:
      - employees
      summary: List employees
      description: Status value can be provided to filter
      operationId: listEmployees
      parameters:
      - name: status
        in: query
        description: Status value that need to be considered for filter
        required: true
        schema:
          type: string
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Employee'
        400:
          description: Invalid status value
          content: {}
      security:
      - employee_auth:
        - write:employees
        - read:employees
    post:
      tags:
      - employees
      summary: Add a new employee
      operationId: addEmployee
      requestBody:
        description: Employee object that needs to be added to the system
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Employee'
        required: true
      responses:
        201:
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmployeeResponse'
        400:
          description: Invalid input
          content: {}
      security:
      - employee_auth:
        - write:employees
        - read:employees
      x-codegen-request-body-name: body
  /employees/{employeeId}:
    get:
      tags:
      - employees
      summary: Read employee
      description: Returns a single employee
      operationId: getEmployeeById
      parameters:
      - name: employeeId
        in: path
        description: ID of employee to return
        required: true
        schema:
          type: integer
          format: int64
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmployeeResponse'
        400:
          description: Invalid ID supplied
          content: {}
        404:
          description: Employee not found
          content: {}
      security:
      - employee_auth:
        - write:employees
        - read:employees
    post:
      tags:
      - employees
      summary: Update an existing employee or delete this
      operationId: updateEmployee
      parameters:
      - name: employeeId
        in: path
        description: ID of employee to return
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        description: Employe object that needs to be added to the system
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Employee'
        required: true
      responses:
        400:
          description: Invalid ID supplied
          content: {}
        404:
          description: Employee not found
          content: {}
        405:
          description: Validation exception
          content: {}
      security:
      - employee_auth:
        - write:employees
        - read:employees
      x-codegen-request-body-name: body
components:
  schemas:
    Employee:
      required:
      - first_name
      - last_name
      type: object
      properties:
        first_name:
          type: string
        last_name:
          type: string
        status:
          type: string
          description: Employe status in the system
          enum:
          - ENABLED
          - DISABLED
    EmployeeResponse:
      required:
      - first_name
      - last_name
      type: object
      properties:
        id:
          type: integer
          format: int64
        first_name:
          type: string
        last_name:
          type: string
        status:
          type: string
          description: Employe status in the system
          enum:
          - ENABLED
          - DISABLED
  securitySchemes:
    employee_auth:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: http://employees.swagger.io/oauth/dialog
          scopes:
            write:employees: modify employes in your account
            read:employees: read your employes