WIP: support openapi spec version 3

.gitignore

@@ -11,3 +11,4 @@ htmlcov/
 *.swp
 .tox/
 .idea/
+.pytest_cache/

README.rst

@@ -397,8 +397,10 @@ parameters to the underlying `werkzeug`_ server.
 The Swagger UI Console
 ----------------------
 
-The Swagger UI for an API is available, by default, in
-``{base_path}/ui/`` where ``base_path`` is the base path of the API.
+The Swagger UI for an API is available through pip extras.
+You can install it with ``pip install connexion[swagger-ui]``.
+It will be served up at ``{base_path}/ui/`` where ``base_path`` is the
+base path of the API.
 
 You can disable the Swagger UI at the application level:
 
@@ -417,20 +419,32 @@ You can also disable it at the API level:
  app.add_api('my_api.yaml', swagger_ui=False)
 
 If necessary, you can explicitly specify the path to the directory with
-swagger-ui to not use the connexion-embedded swagger-ui distro.
+swagger-ui to not use the connexion[swagger-ui] distro.
 In order to do this, you should specify the following option:
 
 .. code-block:: python
 
  options = {'swagger_path': '/path/to/swagger_ui/'}
  app = connexion.App(__name__, specification_dir='swagger/', options=options)
 
-Make sure that ``swagger_ui/index.html`` loads by default local swagger json.
-You can use the ``api_url`` jinja variable for this purpose:
+If you wish to provide your own swagger-ui distro, note that connextion
+expects a jinja2 file called ``swagger_ui/index.j2`` in order to load the
+correct ``swagger.json`` by default. Your ``index.j2`` file can use the
+``openapi_spec_url`` jinja variable for this purpose:
 
 .. code-block::
 
- const ui = SwaggerUIBundle({ url: "{{ api_url }}/swagger.json"})
+ const ui = SwaggerUIBundle({ url: "{{ openapi_spec_url }}"})
+
+Additionally, if you wish to use swagger-ui-3.x.x, it is also provided by
+installing connexion[swagger-ui], and can be enabled like this:
+
+.. code-block:: python
+
+ from swagger_ui_bundle import swagger_ui_3_path
+ options = {'swagger_path': swagger_ui_3_path}
+ app = connexion.App(__name__, specification_dir='swagger/', options=options)
+
 
 Server Backend
 --------------

connexion/apis/abstract.py

@@ -8,20 +8,17 @@
 import jinja2
 import six
 import yaml
-from swagger_spec_validator.validator20 import validate_spec
+from six.moves.urllib.parse import urlparse
 
-from ..exceptions import ResolverError
-from ..operation import Operation
+from ..exceptions import InvalidSpecification, ResolverError
+from ..operations import OpenAPIOperation, Swagger2Operation
 from ..options import ConnexionOptions
 from ..resolver import Resolver
 from ..utils import Jsonifier
 
 MODULE_PATH = pathlib.Path(__file__).absolute().parent.parent
-SWAGGER_UI_PATH = MODULE_PATH / 'vendor' / 'swagger-ui'
 SWAGGER_UI_URL = 'ui'
 
-RESOLVER_ERROR_ENDPOINT_RANDOM_DIGITS = 6
-
 logger = logging.getLogger('connexion.apis.abstract')
 
 
@@ -68,22 +65,10 @@ def __init__(self, specification, base_path=None, arguments=None,
  self.validator_map = validator_map
  self.resolver_error_handler = resolver_error_handler
 
- self.options = ConnexionOptions(old_style_options)
- # options is added last to preserve the highest priority
- self.options = self.options.extend(options)
-
- # TODO: Remove this in later versions (Current version is 1.1.9)
- if base_path is None and 'base_url' in old_style_options:
- base_path = old_style_options['base_url']
- logger.warning("Parameter base_url should be no longer used. Use base_path instead.")
-
  logger.debug('Loading specification: %s', specification,
  extra={'swagger_yaml': specification,
  'base_path': base_path,
  'arguments': arguments,
- 'swagger_ui': self.options.openapi_console_ui_available,
- 'swagger_path': self.options.openapi_console_ui_from_dir,
- 'swagger_url': self.options.openapi_console_ui_path,
  'auth_all_paths': auth_all_paths})
 
  if isinstance(specification, dict):
@@ -95,6 +80,22 @@ def __init__(self, specification, base_path=None, arguments=None,
  self.specification = compatibility_layer(self.specification)
  logger.debug('Read specification', extra={'spec': self.specification})
 
+ self.spec_version = self._get_spec_version(self.specification)
+
+ self.options = ConnexionOptions(old_style_options, oas_version=self.spec_version)
+ # options is added last to preserve the highest priority
+ self.options = self.options.extend(options)
+
+ # TODO: Remove this in later versions (Current version is 1.1.9)
+ if base_path is None and 'base_url' in old_style_options:
+ base_path = old_style_options['base_url']
+ logger.warning("Parameter base_url should be no longer used. Use base_path instead.")
+
+ logger.debug('Options Loaded',
+ extra={'swagger_ui': self.options.openapi_console_ui_available,
+ 'swagger_path': self.options.openapi_console_ui_from_dir,
+ 'swagger_url': self.options.openapi_console_ui_path})
+
  # Avoid validator having ability to modify specification
  spec = copy.deepcopy(self.specification)
  self._validate_spec(spec)
@@ -116,6 +117,7 @@ def __init__(self, specification, base_path=None, arguments=None,
  logger.debug('Security Definitions: %s', self.security_definitions)
 
  self.definitions = self.specification.get('definitions', {})
+ self.components = self.specification.get('components', {})
  self.parameter_definitions = self.specification.get('parameters', {})
  self.response_definitions = self.specification.get('responses', {})
 
@@ -131,7 +133,7 @@ def __init__(self, specification, base_path=None, arguments=None,
  self.pythonic_params = pythonic_params
 
  if self.options.openapi_spec_available:
- self.add_swagger_json()
+ self.add_openapi_json()
 
  if self.options.openapi_console_ui_available:
  self.add_swagger_ui()
@@ -142,20 +144,34 @@ def __init__(self, specification, base_path=None, arguments=None,
  self.add_auth_on_not_found(self.security, self.security_definitions)
 
  def _validate_spec(self, spec):
+ if self.spec_version < (3, 0, 0):
+ logger.info('Using Swagger 2.0 specification')
+ from openapi_spec_validator import validate_v2_spec as validate_spec
+ else:
+ logger.info('Using OpenApi %d.%d.%d specification' % self.spec_version)
+ from openapi_spec_validator import validate_v3_spec as validate_spec
  validate_spec(spec)
 
  def _set_base_path(self, base_path):
  # type: (AnyStr) -> None
  if base_path is None:
  self.base_path = canonical_base_path(self.specification.get('basePath', ''))
+ if self.spec_version >= (3, 0, 0):
+ # TODO variable subsitution in urls for oas3
+ servers = self.specification.get('servers', [])
+ for server in servers:
+ # TODO how to handle multiple servers in an oas3 spec with different paths?
+ self.base_path = canonical_base_path(urlparse(server['url']).path)
+ break
  else:
  self.base_path = canonical_base_path(base_path)
  self.specification['basePath'] = base_path
 
  @abc.abstractmethod
- def add_swagger_json(self):
+ def add_openapi_json(self):
  """
- Adds swagger json to {base_path}/swagger.json
+ Adds openapi spec to {base_path}/openapi.json
+ (or {base_path}/swagger.json for swagger2)
  """
 
  @abc.abstractmethod
@@ -187,24 +203,40 @@ def add_operation(self, method, path, swagger_operation, path_parameters):
  :type path: str
  :type swagger_operation: dict
  """
- operation = Operation(self,
- method=method,
- path=path,
- path_parameters=path_parameters,
- operation=swagger_operation,
- app_produces=self.produces,
- app_consumes=self.consumes,
- app_security=self.security,
- security_definitions=self.security_definitions,
- definitions=self.definitions,
- parameter_definitions=self.parameter_definitions,
- response_definitions=self.response_definitions,
- validate_responses=self.validate_responses,
- validator_map=self.validator_map,
- strict_validation=self.strict_validation,
- resolver=self.resolver,
- pythonic_params=self.pythonic_params,
- uri_parser_class=self.options.uri_parser_class)
+ if self.spec_version < (3, 0, 0):
+ operation = Swagger2Operation(self,
+ method=method,
+ path=path,
+ path_parameters=path_parameters,
+ operation=swagger_operation,
+ app_produces=self.produces,
+ app_consumes=self.consumes,
+ app_security=self.security,
+ security_definitions=self.security_definitions,
+ definitions=self.definitions,
+ parameter_definitions=self.parameter_definitions,
+ response_definitions=self.response_definitions,
+ validate_responses=self.validate_responses,
+ validator_map=self.validator_map,
+ strict_validation=self.strict_validation,
+ resolver=self.resolver,
+ pythonic_params=self.pythonic_params,
+ uri_parser_class=self.options.uri_parser_class)
+ else:
+ operation = OpenAPIOperation(self,
+ method=method,
+ path=path,
+ operation=swagger_operation,
+ path_parameters=path_parameters,
+ app_security=self.security,
+ components=self.components,
+ validate_responses=self.validate_responses,
+ validator_map=self.validator_map,
+ strict_validation=self.strict_validation,
+ resolver=self.resolver,
+ pythonic_params=self.pythonic_params,
+ uri_parser_class=self.options.uri_parser_class)
+
  self._add_operation_internal(method, path, operation)
 
  @abc.abstractmethod
@@ -219,18 +251,8 @@ def _add_resolver_error_handler(self, method, path, err):
  Adds a handler for ResolverError for the given method and path.
  """
  operation = self.resolver_error_handler(err,
- method=method,
- path=path,
- app_produces=self.produces,
- app_security=self.security,
- security_definitions=self.security_definitions,
- definitions=self.definitions,
- parameter_definitions=self.parameter_definitions,
- response_definitions=self.response_definitions,
- validate_responses=self.validate_responses,
- strict_validation=self.strict_validation,
- resolver=self.resolver,
- randomize_endpoint=RESOLVER_ERROR_ENDPOINT_RANDOM_DIGITS)
+ security=self.security,
+ security_definitions=self.security_definitions)
  self._add_operation_internal(method, path, operation)
 
  def add_paths(self, paths=None):
@@ -287,6 +309,20 @@ def load_spec_from_file(self, arguments, specification):
  swagger_string = jinja2.Template(swagger_template).render(**arguments)
  return yaml.safe_load(swagger_string) # type: dict
 
+ def _get_spec_version(self, spec):
+ try:
+ version_string = spec.get('openapi') or spec.get('swagger')
+ except AttributeError:
+ raise InvalidSpecification('Unable to get spec version')
+ if version_string is None:
+ raise InvalidSpecification('Unable to get spec version')
+ try:
+ version_tuple = tuple(map(int, version_string.split(".")))
+ except TypeError:
+ # unable to convert to semver tuple
+ raise InvalidSpecification('Invalid Spec Version')
+ return version_tuple
+
  @classmethod
  @abc.abstractmethod
  def get_request(self, *args, **kwargs):

connexion/apis/aiohttp_api.py

@@ -64,19 +64,21 @@ def _set_base_path(self, base_path):
  def normalize_string(string):
  return re.sub(r'[^a-zA-Z0-9]', '_', string.strip('/'))
 
- def add_swagger_json(self):
+ def add_openapi_json(self):
  """
- Adds swagger json to {base_path}/swagger.json
+ Adds openapi json to {base_path}/openapi.json
+ (or {base_path}/swagger.json for swagger2)
  """
- logger.debug('Adding swagger.json: %s/swagger.json', self.base_path)
+ logger.debug('Adding spec json: %s/%s', self.base_path,
+ self.options.openapi_spec_path)
  self.subapp.router.add_route(
  'GET',
- '/swagger.json',
- self._get_swagger_json
+ self.options.openapi_spec_path,
+ self._get_openapi_json
  )
 
  @asyncio.coroutine
- def _get_swagger_json(self, req):
+ def _get_openapi_json(self, req):
  return web.Response(
  status=200,
  content_type='application/json',
@@ -109,10 +111,11 @@ def add_swagger_ui(self):
  name='swagger_ui_static'
  )
 
- @aiohttp_jinja2.template('index.html')
+ @aiohttp_jinja2.template('index.j2')
  @asyncio.coroutine
  def _get_swagger_ui_home(self, req):
- return {'api_url': self.base_path}
+ return {'openapi_spec_url': (self.base_path +
+ self.options.openapi_spec_path)}
 
  def add_auth_on_not_found(self, security, security_definitions):
  """

connexion/apis/flask_api.py

@@ -26,13 +26,15 @@ def _set_blueprint(self):
  self.blueprint = flask.Blueprint(endpoint, __name__, url_prefix=self.base_path,
  template_folder=str(self.options.openapi_console_ui_from_dir))
 
- def add_swagger_json(self):
+ def add_openapi_json(self):
  """
- Adds swagger json to {base_path}/swagger.json
+ Adds spec json to {base_path}/swagger.json
+ or {base_path}/openapi.json (for oas3)
  """
- logger.debug('Adding swagger.json: %s/swagger.json', self.base_path)
- endpoint_name = "{name}_swagger_json".format(name=self.blueprint.name)
- self.blueprint.add_url_rule('/swagger.json',
+ logger.debug('Adding spec json: %s/%s', self.base_path,
+ self.options.openapi_spec_path)
+ endpoint_name = "{name}_openapi_json".format(name=self.blueprint.name)
+ self.blueprint.add_url_rule(self.options.openapi_spec_path,
  endpoint_name,
  lambda: flask.jsonify(self.specification))
 
@@ -279,7 +281,10 @@ def console_ui_home(self):
 
  :return:
  """
- return flask.render_template('index.html', api_url=self.base_path)
+ return flask.render_template(
+ 'index.j2',
+ openapi_spec_url=(self.base_path + self.options.openapi_spec_path)
+ )
 
  def console_ui_static_files(self, filename):
  """

connexion/apps/abstract.py

@@ -161,10 +161,6 @@ def add_api(self, specification, base_path=None, arguments=None,
 
  def _resolver_error_handler(self, *args, **kwargs):
  from connexion.handlers import ResolverErrorHandler
- kwargs['operation'] = {
- 'operationId': 'connexion.handlers.ResolverErrorHandler',
- }
- kwargs.setdefault('app_consumes', ['application/json'])
  return ResolverErrorHandler(self.api_cls, self.resolver_error, *args, **kwargs)
 
  def add_url_rule(self, rule, endpoint=None, view_func=None, **options):