I want to add new Endpoint

Structure and placement in .yaml

Endpoints are placed inside path attribute. Each endpoint can be defined as a separate file and stored in ./openapi/paths/ as a .yaml. Then the definition in main .yaml looks like this:

paths:
  '/users/{username}':
    $ref: 'paths/users@{username}.yaml'
  /echo:
    $ref: paths/echo.yaml

This is an efficient way of creating paths that can be reused in multiple versions of the documentation. This way you can reuse the same $refs when the new version doesn't affect it.

Endpoint methods

Each endpoint can have multiple HTTP methods:

# inside paths/users@{username}.yaml
put:
  [PUT /users/{username} definition]
get:
  [GET /users/{username} definition]

Every definition looks the same but only some fields are required:

  tags:
    - User
  summary: Get user by user name
  description: |
    Some description of the operation.
    You can use `Markdown` here.
  operationId: getUserByName
  parameters:
    - name: username
      in: path
      description: The name that needs to be fetched
      required: true
      schema:
        type: string
  responses:
    '200':
      description: Success
      content:
        application/json:
          schema:
            $ref: ../components/schemas/User.yaml
          example:
            username: user1
            email: [email protected]

You can find more details on https://swagger.io/specification/#operation-object.