Swagger: Specify security like basic, oauth2

'securitySchemes' element is used to define the security scheme that is used by the APIs.

components:
  securitySchemes:
    myOauth:
      type: oauth2
      flows:
        password:
          tokenUrl: 'http://sample.com/token'
          scopes:
            write: Used to modify resources
            read: Used to read resources
            
    myBasic:
      type: http
      scheme: basic

You can use the defined security scheme in the APIs like below.

  /employees/{employeeId}:
    get:
      security:
        - myBasic: []

/employees:
      post:
        security: 
          - myOauth: [write]

data.yaml

openapi: 3.0.0
info:
  title: Customer Data Aceess API
  description: API to expose all the CRUD operations on  customers
  contact:
    name: Krishna
    email: krishna123@abc.com
    url: https://self-learning-java-tutorial.blogspot.com/
  version: 1.0.0
paths:

  /employees/{employeeId}:
    get:
      security:
        - myBasic: []
      parameters: 
      - in: path
        name: employeeId
        required: true
        schema:
          type: integer
          example: 123
      responses:
        200:
          description: Get Specific Employee Details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/employee'
            application/xml:
              schema:
                $ref: '#/components/schemas/employee'
            application/csv:
              schema:
                $ref: '#/components/schemas/employee'
        403:
          $ref: '#/components/responses/403Unauthorized'
        500:
          $ref: '#/components/responses/500InternalServerError'
          
  /employees:
      post:
        security: 
          - myOauth: [write]
        description: Add new employee to the organization
        requestBody:
          content:
            application/json:
              schema:
                type: object
                properties:
                  firstName:
                    type: string
                    example: krishna
                  lastName:
                    type: string
                    example: gurram
        responses:
          201:
            description: New Employee is created
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/employee'
          403:
            $ref: '#/components/responses/403Unauthorized'
          500:
            $ref: '#/components/responses/500InternalServerError'
                  
      get:
        parameters: 
          - $ref: '#/components/parameters/pageSize'
          - $ref: '#/components/parameters/pageNumber'
          - in: header
            name: onetime_token
            description: token to be used at the time of login
            required: false
            schema:
              type: string
              example: 08c3372a-9314-49d6-b9dd-ff212c1715a5
        responses:
          200:
            description: List of all the employees in organization
            content:
               application/json:
                  schema:
                    type: array
                    items:
                      $ref: '#/components/schemas/employee'
          403:
            $ref: '#/components/responses/403Unauthorized'
          500:
            $ref: '#/components/responses/500InternalServerError'

components:
  securitySchemes:
    myOauth:
      type: oauth2
      flows:
        password:
          tokenUrl: 'http://sample.com/token'
          scopes:
            write: Used to modify resources
            read: Used to read resources
            
    myBasic:
      type: http
      scheme: basic
      
  parameters:
    pageSize:  
      in: query
      name: size
      description: Number of elements to return
      required: false
      schema:
        type: integer
        example: 10
        minimum: 10
        maximum: 100
        
    pageNumber:
      in: query
      name: from
      description: Page number to return
      required: true
      schema:
        type: integer
        example: 1
        
  responses:
    403Unauthorized:
      description: User do not have permission to access this API
      content:
        application/json:
          schema:
            type: object
            properties:
              statusCode:
                type: integer
                example: 403
              message:
                type: string
                example: Unauthorized
    500InternalServerError:
      description: Unable to process the request
      content:
        application/json:
          schema:
            type: object
            properties:
              statusCode:
                type: integer
                example: 500
              message:
                type: string
                example: Internal Server Error
    404NotFoundError:
      description: Service Not Found
      content:
        application/json:
          schema:
            type: object
            properties:
              statusCode:
                type: integer
                example: 404
              message:
                type: string
                example: Service not found
  schemas:
    employee:
      type: object
      required: 
        - firstName
        - id
      properties:
        id:
          type: integer
          example: 1234
        firstName:
          type: string
          example: krishna
        lastName:
          type: string
          example: gurram

Open the content of data.yaml in swagger editor, you can see the security is enabled (lock icon) for below APIs.

GET /employees​/{employeeId}

POST /employees

Previous                                                    Next                                                    Home