Allow opt-in to new api name restrictions. (#144)

Author: inklesspen

endpoints/_endpointscfg_impl.py

@@ -151,7 +151,7 @@ def _WriteFile(output_path, name, content):
 
 
 def GenApiConfig(service_class_names, config_string_generator=None,
-                 hostname=None, application_path=None):
+                 hostname=None, application_path=None, **additional_kwargs):
   """Write an API configuration for endpoints annotated ProtoRPC services.
 
   Args:
@@ -211,7 +211,7 @@ def GenApiConfig(service_class_names, config_string_generator=None,
     # Map each API by name-version.
     service_map['%s-%s' % api_info] = (
         config_string_generator.pretty_print_config_to_json(
-            services, hostname=hostname))
+            services, hostname=hostname, **additional_kwargs))
 
   return service_map
 
@@ -311,7 +311,7 @@ def _GenDiscoveryDoc(service_class_names, doc_format,
 
 
 def _GenOpenApiSpec(service_class_names, output_path, hostname=None,
-                    application_path=None):
+                    application_path=None, x_google_api_name=False):
   """Write discovery documents generated from a cloud service to file.
 
   Args:
@@ -329,7 +329,8 @@ def _GenOpenApiSpec(service_class_names, output_path, hostname=None,
   service_configs = GenApiConfig(
       service_class_names, hostname=hostname,
       config_string_generator=openapi_generator.OpenApiGenerator(),
-      application_path=application_path)
+      application_path=application_path,
+      x_google_api_name=x_google_api_name)
   for api_name_version, config in service_configs.iteritems():
     openapi_name = api_name_version.replace('-', '') + 'openapi.json'
     output_files.append(_WriteFile(output_path, openapi_name, config))
@@ -484,7 +485,8 @@ def _GenOpenApiSpecCallback(args, openapi_func=_GenOpenApiSpec):
   """
   openapi_paths = openapi_func(args.service, args.output,
                                hostname=args.hostname,
-                               application_path=args.application)
+                               application_path=args.application,
+                               x_google_api_name=args.x_google_api_name)
   for openapi_path in openapi_paths:
     print 'OpenAPI spec written to %s' % openapi_path
 
@@ -572,6 +574,8 @@ def AddStandardOptions(parser, *args):
   get_openapi_spec.set_defaults(callback=_GenOpenApiSpecCallback)
   AddStandardOptions(get_openapi_spec, 'application', 'hostname', 'output',
                      'service')
+  get_openapi_spec.add_argument('--x-google-api-name', action='store_true',
+                                help="Add the 'x-google-api-name' field to the generated spec")
 
   # Create an alias for get_openapi_spec called get_swagger_spec to support
   # the old-style naming. This won't be a visible command, but it will still

endpoints/api_config.py

@@ -258,17 +258,6 @@ def _CheckLimitDefinitions(limit_definitions):
       _CheckType(ld.default_limit, int, 'limit_definition.default_limit')
 
 
-_VALID_API_NAME = re.compile('^[a-z][a-z0-9]{0,39}$')
-
-
-def _CheckApiName(name):
-  valid = (_VALID_API_NAME.match(name) is not None)
-  if not valid:
-    raise api_exceptions.InvalidApiNameException(
-        'The API name must match the regular expression {}'.format(
-            _VALID_API_NAME.pattern[1:-1]))
-
-
 # pylint: disable=g-bad-name
 class _ApiInfo(object):
   """Configurable attributes of an API.
@@ -592,7 +581,6 @@ def __init__(self, name, version, description=None, hostname=None,
         limit_definitions: list of LimitDefinition tuples used in this API.
       """
       _CheckType(name, basestring, 'name', allow_none=False)
-      _CheckApiName(name)
       _CheckType(version, basestring, 'version', allow_none=False)
       _CheckType(description, basestring, 'description')
       _CheckType(hostname, basestring, 'hostname')

endpoints/openapi_generator.py

@@ -45,6 +45,18 @@
 _DEFAULT_SECURITY_DEFINITION = 'google_id_token'
 
 
+_VALID_API_NAME = re.compile('^[a-z][a-z0-9]{0,39}$')
+
+
+def _validate_api_name(name):
+  valid = (_VALID_API_NAME.match(name) is not None)
+  if not valid:
+    raise api_exceptions.InvalidApiNameException(
+        'The API name must match the regular expression {}'.format(
+            _VALID_API_NAME.pattern[1:-1]))
+  return name
+
+
 class OpenApiGenerator(object):
   """Generates an OpenAPI spec from a ProtoRPC service.
 
@@ -845,7 +857,7 @@ def __get_merged_api_info(self, services):
 
     return merged_api_info
 
-  def __api_openapi_descriptor(self, services, hostname=None):
+  def __api_openapi_descriptor(self, services, hostname=None, x_google_api_name=False):
     """Builds an OpenAPI description of an API.
 
     Args:
@@ -866,7 +878,8 @@ def __api_openapi_descriptor(self, services, hostname=None):
     """
     merged_api_info = self.__get_merged_api_info(services)
     descriptor = self.get_descriptor_defaults(merged_api_info,
-                                              hostname=hostname)
+                                              hostname=hostname,
+                                              x_google_api_name=x_google_api_name)
 
     description = merged_api_info.description
     if not description and len(services) == 1:
@@ -956,7 +969,7 @@ def __api_openapi_descriptor(self, services, hostname=None):
 
     return descriptor
 
-  def get_descriptor_defaults(self, api_info, hostname=None):
+  def get_descriptor_defaults(self, api_info, hostname=None, x_google_api_name=False):
     """Gets a default configuration for a service.
 
     Args:
@@ -980,17 +993,19 @@ def get_descriptor_defaults(self, api_info, hostname=None):
             'version': api_info.api_version,
             'title': api_info.name
         },
-        'x-google-api-name': api_info.name,
         'host': hostname,
         'consumes': ['application/json'],
         'produces': ['application/json'],
         'schemes': [protocol],
         'basePath': base_path,
     }
 
+    if x_google_api_name:
+        defaults['x-google-api-name'] = _validate_api_name(api_info.name)
+
     return defaults
 
-  def get_openapi_dict(self, services, hostname=None):
+  def get_openapi_dict(self, services, hostname=None, x_google_api_name=False):
     """JSON dict description of a protorpc.remote.Service in OpenAPI format.
 
     Args:
@@ -1012,9 +1027,9 @@ def get_openapi_dict(self, services, hostname=None):
     util.check_list_type(services, remote._ServiceClass, 'services',
                          allow_none=False)
 
-    return self.__api_openapi_descriptor(services, hostname=hostname)
+    return self.__api_openapi_descriptor(services, hostname=hostname, x_google_api_name=x_google_api_name)
 
-  def pretty_print_config_to_json(self, services, hostname=None):
+  def pretty_print_config_to_json(self, services, hostname=None, x_google_api_name=False):
     """JSON string description of a protorpc.remote.Service in OpenAPI format.
 
     Args:
@@ -1026,7 +1041,7 @@ def pretty_print_config_to_json(self, services, hostname=None):
     Returns:
       string, The OpenAPI descriptor document as a JSON string.
     """
-    descriptor = self.get_openapi_dict(services, hostname)
+    descriptor = self.get_openapi_dict(services, hostname, x_google_api_name=x_google_api_name)
     return json.dumps(descriptor, sort_keys=True, indent=2,
                       separators=(',', ': '))
 

endpoints/test/api_config_test.py

@@ -17,7 +17,6 @@
 import itertools
 import json
 import unittest
-import pytest
 
 import endpoints.api_config as api_config
 from endpoints.api_config import ApiConfigGenerator
@@ -2110,28 +2109,6 @@ class MyDecoratedService3(remote.Service):
     self.assertEqual([MyDecoratedService1, MyDecoratedService2,
                       MyDecoratedService3], my_api.get_api_classes())
 
-  def testApiNameRestrictions(self):
-
-    @api_config.api(name='coolservice', version='vX')
-    class MyDecoratedService(remote.Service):
-      """Describes MyDecoratedService."""
-      pass
-
-    api_info = MyDecoratedService.api_info
-    assert 'coolservice' == api_info.name
-
-    with pytest.raises(api_exceptions.InvalidApiNameException):
-      @api_config.api('CoolService2', 'v2')
-      class MyDecoratedService(remote.Service):
-        """Describes MyDecoratedService."""
-        pass
-
-    with pytest.raises(api_exceptions.InvalidApiNameException):
-      @api_config.api('c' + 'o'*40 + 'l', 'v2')
-      class MyDecoratedService(remote.Service):
-        """Describes MyDecoratedService."""
-        pass
-
 class MethodDecoratorTest(unittest.TestCase):
 
   def testMethodId(self):

endpoints/test/openapi_generator_test.py

@@ -16,13 +16,15 @@
 
 import json
 import unittest
+import pytest
 
 import endpoints.api_config as api_config
 
 from protorpc import message_types
 from protorpc import messages
 from protorpc import remote
 
+import endpoints.api_exceptions as api_exceptions
 import endpoints.resource_container as resource_container
 import endpoints.openapi_generator as openapi_generator
 import test_util
@@ -154,7 +156,6 @@ def entries_post_audiences(self, unused_request):
             'description': 'Describes MyService.',
             'version': 'v1',
         },
-        'x-google-api-name': 'root',
         'host': 'example.appspot.com',
         'consumes': ['application/json'],
         'produces': ['application/json'],
@@ -481,7 +482,6 @@ def items_put_container(self, unused_request):
             'description': 'Describes MyService.',
             'version': 'v1',
         },
-        'x-google-api-name': 'root',
         'host': 'example.appspot.com',
         'consumes': ['application/json'],
         'produces': ['application/json'],
@@ -1033,7 +1033,6 @@ def get_airport_2(self, request):
             'title': 'iata',
             'version': 'v1',
         },
-        'x-google-api-name': 'iata',
         'host': None,
         'consumes': ['application/json'],
         'produces': ['application/json'],
@@ -1127,7 +1126,6 @@ def noop_get(self, unused_request):
             'description': 'Describes MyService.',
             'version': 'v1',
         },
-        'x-google-api-name': 'root',
         'host': 'localhost:8080',
         'consumes': ['application/json'],
         'produces': ['application/json'],
@@ -1191,7 +1189,6 @@ def noop_get(self, unused_request):
             'description': 'Describes MyService.',
             'version': 'v1',
         },
-        'x-google-api-name': 'root',
         'host': 'example.appspot.com',
         'consumes': ['application/json'],
         'produces': ['application/json'],
@@ -1292,7 +1289,6 @@ def override_get(self, unused_request):
             'description': 'Describes MyService.',
             'version': 'v1',
         },
-        'x-google-api-name': 'root',
         'host': 'example.appspot.com',
         'consumes': ['application/json'],
         'produces': ['application/json'],
@@ -1365,7 +1361,6 @@ def noop_get(self, unused_request):
             'description': 'Describes MyService.',
             'version': '1.3.4',
         },
-        'x-google-api-name': 'root',
         'host': 'example.appspot.com',
         'consumes': ['application/json'],
         'produces': ['application/json'],
@@ -1418,7 +1413,6 @@ def noop_get(self, unused_request):
             'description': 'Describes MyService.',
             'version': 'v1',
         },
-        'x-google-api-name': 'root',
         'host': 'example.appspot.com',
         'consumes': ['application/json'],
         'produces': ['application/json'],
@@ -1471,7 +1465,6 @@ def noop_get(self, unused_request):
             'description': 'Describes MyService.',
             'version': 'v1',
         },
-        'x-google-api-name': 'root',
         'host': 'example.appspot.com',
         'consumes': ['application/json'],
         'produces': ['application/json'],
@@ -1524,7 +1517,6 @@ def toplevel(self, unused_request):
             'description': 'Testing repeated params',
             'version': 'v1',
         },
-        'x-google-api-name': 'root',
         'host': 'example.appspot.com',
         'consumes': ['application/json'],
         'produces': ['application/json'],
@@ -1606,7 +1598,6 @@ def toplevel(self, unused_request):
             'description': 'Testing repeated simple field params',
             'version': 'v1',
         },
-        'x-google-api-name': 'root',
         'host': 'example.appspot.com',
         'consumes': ['application/json'],
         'produces': ['application/json'],
@@ -1682,7 +1673,6 @@ def toplevel(self, unused_request):
             'description': 'Testing repeated Message params',
             'version': 'v1',
         },
-        'x-google-api-name': 'root',
         'host': 'example.appspot.com',
         'consumes': ['application/json'],
         'produces': ['application/json'],
@@ -1749,6 +1739,35 @@ def toplevel(self, unused_request):
 
     test_util.AssertDictEqual(expected_openapi, api, self)
 
+  def testApiNameRestrictions(self):
+    @api_config.api(name='coolservice', version='vX')
+    class MyDecoratedService(remote.Service):
+      pass
+
+    api = json.loads(self.generator.pretty_print_config_to_json(MyDecoratedService))
+    assert 'x-google-api-name' not in api
+    api = json.loads(self.generator.pretty_print_config_to_json(MyDecoratedService, x_google_api_name=True))
+    assert 'x-google-api-name' in api
+    assert 'coolservice' == api['x-google-api-name']
+
+    @api_config.api('CoolService2', 'v2')
+    class MyDecoratedService(remote.Service):
+      pass
+
+    api = json.loads(self.generator.pretty_print_config_to_json(MyDecoratedService))
+    assert 'x-google-api-name' not in api
+    with pytest.raises(api_exceptions.InvalidApiNameException):
+      self.generator.pretty_print_config_to_json(MyDecoratedService, x_google_api_name=True)
+
+    @api_config.api('c' + 'o'*40 + 'l', 'v2')
+    class MyDecoratedService(remote.Service):
+      pass
+
+    api = json.loads(self.generator.pretty_print_config_to_json(MyDecoratedService))
+    assert 'x-google-api-name' not in api
+    with pytest.raises(api_exceptions.InvalidApiNameException):
+      self.generator.pretty_print_config_to_json(MyDecoratedService, x_google_api_name=True)
+
 
 class DevServerOpenApiGeneratorTest(BaseOpenApiGeneratorTest,
                                     test_util.DevServerTest):
@@ -1780,7 +1799,6 @@ def noop_get(self, unused_request):
             'description': 'Describes MyService.',
             'version': 'v1',
         },
-        'x-google-api-name': 'root',
         'host': 'example.appspot.com',
         'consumes': ['application/json'],
         'produces': ['application/json'],
@@ -1846,7 +1864,6 @@ def entries_post_audience(self, unused_request):
             'description': 'Describes MyService.',
             'version': 'v1',
         },
-        'x-google-api-name': 'root',
         'host': 'example.appspot.com',
         'consumes': ['application/json'],
         'produces': ['application/json'],
@@ -2044,7 +2061,6 @@ def entries_post(self, unused_request):
             'description': 'Describes MyService.',
             'version': 'v1',
         },
-        'x-google-api-name': 'root',
         'host': 'example.appspot.com',
         'consumes': ['application/json'],
         'produces': ['application/json'],
@@ -2131,7 +2147,6 @@ def entries_post(self, unused_request):
             'description': 'Describes MyService.',
             'version': 'v1',
         },
-        'x-google-api-name': 'root',
         'host': 'example.appspot.com',
         'consumes': ['application/json'],
         'produces': ['application/json'],