Swagger Editor: Adding template or path parameters to the API

Path parameters are used to bind segments of paths to method parameters. Suppose you want to get details of specific employee, usually the url look like following.

/employees/1: Gives you details of employee with id 1.

/employees/2: Givens you details of employee with id 2.

Example

paths:
  /employees/{employeeId}:
    get:
      parameters: 
      - in: path
        name: employeeId
        required: true
        schema:
          type: integer
          example: 123
      responses:
        200:
          description: Get Specific Employee Details
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    example: 123
                  name:
                    type: string
                    example: Krishna

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:
      parameters: 
      - in: path
        name: employeeId
        required: true
        schema:
          type: integer
          example: 123
      responses:
        200:
          description: Get Specific Employee Details
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    example: 123
                  name:
                    type: string
                    example: krishna
  /employees:
      get:
        parameters: 
          - in: query
            name: from
            description: Page number to return
            required: true
            schema:
              type: integer
              example: 1
          - in: query
            name: size
            description: Number of elements to return
            required: false
            schema:
              type: integer
              example: 10
              minimum: 10
              maximum: 100
        responses:
          200:
            description: List of all the employees in organization
            content:
               application/json:
                  schema:
                    type: array
                    items:
                      properties:
                        id:
                          type: integer
                          example: 1234
                        name:
                          type: string
                          example: Krishna

Copy the content of data.yaml to Swagger Editor, you can see the API definition at right side of the window.

Previous                                                    Next                                                    Home