api-ref: fix mention of all_tenants filter for non-admins

The API reference for listing servers says that the all_tenants
filter parameter is available for non-admins which is likely
a mistake because of it being in the _get_server_search_options
method, but all_tenants is admin-only by default policy because
of the os_compute_api:servers:index:get_all_tenants and
os_compute_api:servers:detail:get_all_tenants policy rules.

This change fixes the API reference to remove all_tenants from
the list of non-admin filter parameters and also adds a note to
the _get_server_search_options method to avoid future confusion.

Change-Id: I0e937afbdf8e19d2efd626047913d4c8a9b88b76
Closes-Bug: #1828042

api-ref/source/servers.inc

@@ -156,7 +156,6 @@ whitelist will be silently ignored.
 - For non-admin users, whitelist is different from admin users whitelist.
   Valid whitelist for non-admin users includes
 
-  - ``all_tenants``
   - ``changes-since``
   - ``flavor``
   - ``image``

nova/api/openstack/compute/servers.py

@@ -1212,6 +1212,11 @@ class ServersController(wsgi.Controller):
 
     def _get_server_search_options(self, req):
         """Return server search options allowed by non-admin."""
+        # NOTE(mriedem): all_tenants is admin-only by default but because of
+        # tight-coupling between this method, the remove_invalid_options method
+        # and how _get_servers uses them, we include all_tenants here but it
+        # will be removed later for non-admins. Fixing this would be nice but
+        # probably not trivial.
         opt_list = ('reservation_id', 'name', 'status', 'image', 'flavor',
                     'ip', 'changes-since', 'all_tenants')
         if api_version_request.is_supported(req, min_version='2.5'):