[docs] add examples to events and tag to ingress port (#3552)

management/server/http/api/openapi.yml

@@ -1687,7 +1687,6 @@ components:
         - connected
         - fallback
         - region
-
     AvailablePorts:
       type: object
       properties:
@@ -1785,7 +1784,7 @@ components:
         ingress_ip:
           description: Ingress IP address of the ingress peer where the traffic arrives
           type: string
-          example:
+          example: 192.34.0.123
         port_range_mappings:
           description: List of port ranges that are allowed to be used by the ingress peer
           type: array
@@ -1835,9 +1834,11 @@ components:
         city_name:
           type: string
           description: "Name of the city (if known)."
+          example: "Berlin"
         country_code:
           type: string
           description: "ISO country code (if known)."
+          example: "DE"
       required:
         - city_name
         - country_code
@@ -1847,18 +1848,22 @@ components:
         id:
           type: string
           description: "ID of this endpoint (e.g., peer ID or resource ID)."
+          example: "ch8i4ug6lnn4g9hqv7m0"
         type:
           type: string
           description: "Type of the endpoint object (e.g., UNKNOWN, PEER, HOST_RESOURCE)."
+          example: "PEER"
         name:
           type: string
           description: "Name is the name of the endpoint object (e.g., a peer name)."
+          example: "My Peer"
         geo_location:
           $ref: '#/components/schemas/NetworkTrafficLocation'
         os:
           type: string
           nullable: true
           description: "Operating system of the peer, if applicable."
+          example: "Linux"
         address:
           type: string
           description: "IP address (and possibly port) in string form."
@@ -1867,6 +1872,7 @@ components:
           type: string
           nullable: true
           description: "DNS label/name if available."
+          example: "*.mydomain.com"
       required:
         - id
         - type
@@ -1881,65 +1887,83 @@ components:
         id:
           type: string
           description: "ID of the event. Unique."
+          example: "18e204d6-f7c6-405d-8025-70becb216add"
         flow_id:
           type: string
           description: "FlowID is the ID of the connection flow. Not unique because it can be the same for multiple events (e.g., start and end of the connection)."
+          example: "61092452-b17c-4b14-b7cf-a2158c549826"
         reporter_id:
           type: string
           description: "ID of the reporter of the event (e.g., the peer that reported the event)."
+          example: "ch8i4ug6lnn4g9hqv7m0"
         timestamp:
           type: string
           format: date-time
           description: "Timestamp of the event."
+          example: "2025-03-20T16:23:58.125397Z"
         source:
           $ref: '#/components/schemas/NetworkTrafficEndpoint'
         user_id:
           type: string
           nullable: true
           description: "UserID is the ID of the user that initiated the event (can be empty as not every event is user-initiated)."
+          example: "google-oauth2|123456789012345678901"
         user_email:
           type: string
           nullable: true
           description: "Email of the user who initiated the event (if any)."
+          example: "alice@netbird.io"
         user_name:
           type: string
           nullable: true
           description: "Name of the user who initiated the event (if any)."
+          example: "Alice Smith"
         destination:
           $ref: '#/components/schemas/NetworkTrafficEndpoint'
         protocol:
           type: integer
           description: "Protocol is the protocol of the traffic (e.g. 1 = ICMP, 6 = TCP, 17 = UDP, etc.)."
+          example: 6
         type:
           type: string
           description: "Type of the event (e.g. TYPE_UNKNOWN, TYPE_START, TYPE_END, TYPE_DROP)."
+          example: "TYPE_START"
         direction:
           type: string
           description: "Direction of the traffic (e.g. DIRECTION_UNKNOWN, INGRESS, EGRESS)."
+          example: "INGRESS"
         rx_bytes:
           type: integer
           description: "Number of bytes received."
+          example: 1234
         rx_packets:
           type: integer
           description: "Number of packets received."
+          example: 5
         tx_bytes:
           type: integer
           description: "Number of bytes transmitted."
+          example: 1234
         tx_packets:
           type: integer
           description: "Number of packets transmitted."
+          example: 5
         policy_id:
           type: string
           description: "ID of the policy that allowed this event."
+          example: "ch8i4ug6lnn4g9hqv7m0"
         policy_name:
           type: string
           description: "Name of the policy that allowed this event."
+          example: "All to All"
         icmp_type:
           type: integer
           description: "ICMP type (if applicable)."
+          example: 8
         icmp_code:
           type: integer
           description: "ICMP code (if applicable)."
+          example: 0
       required:
         - id
         - flow_id
@@ -2529,7 +2553,7 @@ paths:
   /api/peers/{peerId}/ingress/ports:
     get:
       x-cloud-only: true
-      summary: List all Ingress Port Allocations for a Peer
+      summary: List all Port Allocations
       description: Returns a list of all ingress port allocations for a peer
       tags: [ Ingress Ports ]
       security:
@@ -2566,7 +2590,7 @@ paths:
           "$ref": "#/components/responses/internal_error"
     post:
       x-cloud-only: true
-      summary: Create a Ingress Port Allocation
+      summary: Create a Port Allocation
       description: Creates a new ingress port allocation for a peer
       tags: [ Ingress Ports ]
       security:
@@ -2603,7 +2627,7 @@ paths:
   /api/peers/{peerId}/ingress/ports/{allocationId}:
     get:
       x-cloud-only: true
-      summary: Retrieve a Ingress Port Allocation
+      summary: Retrieve a Port Allocation
       description: Get information about an ingress port allocation
       tags: [ Ingress Ports ]
       security:
@@ -2639,6 +2663,12 @@ paths:
           "$ref": "#/components/responses/internal_error"
     put:
       x-cloud-only: true
+      summary: Update a Port Allocation
+      description: Update information about an ingress port allocation
+      tags: [ Ingress Ports ]
+      security:
+        - BearerAuth: [ ]
+        - TokenAuth: [ ]
       parameters:
         - in: path
           name: peerId
@@ -2675,7 +2705,7 @@ paths:
           "$ref": "#/components/responses/internal_error"
     delete:
       x-cloud-only: true
-      summary: Delete a Ingress Port Allocation
+      summary: Delete a Port Allocation
       description: Delete an ingress port allocation
       tags: [ Ingress Ports ]
       security:
@@ -4156,10 +4186,14 @@ paths:
                 type: array
                 items:
                   $ref: "#/components/schemas/NetworkTrafficEvent"
-        "401":
+        '400':
-          $ref: "#/components/responses/requires_authentication"
+          "$ref": "#/components/responses/bad_request"
-        "500":
+        '401':
-          $ref: "#/components/responses/internal_error"
+          "$ref": "#/components/responses/requires_authentication"
+        '403':
+          "$ref": "#/components/responses/forbidden"
+        '500':
+          "$ref": "#/components/responses/internal_error"
   /api/posture-checks:
     get:
       summary: List all Posture Checks