openapi: improve clients find api docs

heyxkhoa · Jan 26, 2021 · ca9cf3f · ca9cf3f
1 parent f79876e
commit ca9cf3f
Showing 1 changed file with 37 additions and 4 deletions.
diff --git a/openapi/openapi.yaml b/openapi/openapi.yaml
@@ -794,11 +794,17 @@
       'tags':
       - 'clients'
       'operationId': 'clientsFind'
-      'summary': 'Get information about selected clients by their IP address'
+      'summary': >
+        Get information about clients by their IP addresses or client IDs.
       'parameters':
       - 'name': 'ip0'
         'in': 'query'
-        'description': 'Filter by IP address'
+        'description': >
+          Filter by IP address or client IDs.  Parameters with names `ip1`,
+          `ip2`, and so on are also accepted and interpreted as "ip0 OR ip1 OR
+          ip2".
+
+          TODO(a.garipov): Replace with a better query API.
         'schema':
           'type': 'string'
       'responses':
@@ -2179,7 +2185,7 @@
           'type': 'string'
     'ClientsFindResponse':
       'type': 'array'
-      'description': 'Response to clients find operation'
+      'description': 'Client search results.'
       'items':
         '$ref': '#/components/schemas/ClientsFindEntry'
     'AccessListResponse':
@@ -2210,7 +2216,34 @@
       'additionalProperties':
         '$ref': '#/components/schemas/ClientFindSubEntry'
       'example':
-        '1.2.3.4': 'test'
+        'cli42':
+          'name': 'Client 42'
+          'ids': ['cli42']
+          'use_global_settings': true
+          'filtering_enabled': true
+          'parental_enabled': true
+          'safebrowsing_enabled': true
+          'safesearch_enabled': true
+          'use_global_blocked_services': true
+          'blocked_services': null
+          'upstreams': null
+          'whois_info': null
+          'disallowed': false
+          'disallowed_rule': ''
+        '1.2.3.4':
+          'name': 'Client 1-2-3-4'
+          'ids': ['1.2.3.4']
+          'use_global_settings': true
+          'filtering_enabled': true
+          'parental_enabled': true
+          'safebrowsing_enabled': true
+          'safesearch_enabled': true
+          'use_global_blocked_services': true
+          'blocked_services': null
+          'upstreams': null
+          'whois_info': null
+          'disallowed': false
+          'disallowed_rule': ''
     'ClientFindSubEntry':
       'type': 'object'
       'description': 'Client information.'