Finalize 2.0 Release

[dtkav]

Description

We created the dev-2.0 branch to introduce a handful of major breaking changes to connexion.
https://github.com/zalando/connexion/milestone/10

At the time, the two major changes were:

• RefResolver (or its successor) should allow customizing deserialization, not only scheme / retrieval python-jsonschema/referencing#4 openapi 3 support
• Regex python-jsonschema/jsonschema#406 removing vendored swagger-ui

Both of these changes are now in dev-2.0

Next Steps

What other things should be in the 2.0 release? Is it large enough as is? What's could be better?
It would be great to finalize the feature set for Connexion 2.0 and get it shipped! 🚢

Let me know what you think!

[dtkav]

The PR for merging dev-2.0 -> master is python-jsonschema/jsonschema#619

[ioggstream]

I successfully run this development connexion with a non-trivial yaml. Good work!

I now have some issues with

connexion/jsonref.py:from jsonschema import RefResolver

because it can't parse yaml schema files like https://opensource.zalando.com/problem/schema.yaml

I workaround'd it in the jsonschema module

+++ b/jsonschema/validators.py
@@ -2,6 +2,7 @@ from __future__ import division
 
 import contextlib
 import json
+import yaml
 import numbers
 
 try:
@@ -466,12 +467,15 @@ class RefResolver(object):
             # Requests has support for detecting the correct encoding of
             # json over http
             if callable(requests.Response.json):
-                result = requests.get(uri).json()
-            else:
-                result = requests.get(uri).json
+                try:
+                    result = requests.get(uri).json()
+                except ValueError:
+                    result = None
+            if not result:
+               result = yaml.load(requests.get(uri).content)
         else:
             # Otherwise, pass off to urllib and assume utf-8
-            result = json.loads(urlopen(uri).read().decode("utf-8"))
+           result = yaml.load(urlopen(uri).read().decode("utf-8"))
 
         if self.cache_remote:

But on https://github.com/Julian/jsonschema/issues/420 it seems yaml is currently out of scope.

Can we fix it in connexion subclassing RefResolver?

[hjacobs]

@dtkav thanks for the great work!

[dtkav]

Thanks for the bug report @ioggstream ! I'll follow that up in a separate ticket. I'd like to keep this one a bit more of a high-level discussion on what features / breaking changes should make it into Connexion 2.0. (I've hidden your comment, now that its' in python-jsonschema/jsonschema#681 - hope you don't mind!)

@hjacobs and @jmcs , I would love your thoughts especially on high-level next steps!

Thanks to everyone in the community who helped make these features possible ❤️

[hjacobs]

@dtkav I think the 2.0 release should not be bigger as the OpenAPI 3 support is already a monster change. Let's get some feedback from people trying it out and then releasing it with any additional blocker bug fixes we encounter.

@jmcs WDYT? Do we know who could/would try it out and give feedback?

[dtkav]

@hjacobs - I tend to agree. The only other thing I can think might be useful (and a breaking change) is to validate requests/responses depending on mimetype, and not only if the endpoint is purely json (i.e. python-jsonschema/jsonschema#593).
Everything else I can think of can be incremental improvement.

[cziebuhr]

I'm a quite new user of connexion, but I really like the project.
OpenAPI 3 uses JSON Schema Specification Wright Draft 00 (= Draft 5), which is mostly compatible to JSON-Schema Draft 4.
But it points out that "$ref" should only be used wherever a schema is expected. This allows "$ref" to be a valid key for the "properties" keyword. The new resolve_refs function breaks that feature.
Future versions of OpenAPI may use Draft 6 or later, which introduce more incompabilities, e.g. exclusiveMinimum/exclusiveMaximum being a number instead of a boolean.
I therefore want to discuss if it makes sense to have a validator_map per api (add parameter to add_api) instead of having it globally.

In our setup, we already have some extensions to Draft4Validator, regarding x-nullable and readOnly (the first one with a different implementation than here). I will open seperate issues/PRs for discussion about these, but that shouldn't block the 2.0 release.

[ioggstream]

@dtkav I'm running the specs against some files. I'll file separate issues like you did with the yaml stuff, ok?

PS: Thank You for the flash fix!

[cziebuhr]

Can you have a look at dev-2.0...cziebuhr:nullable ? According to OpenAPI 3, nullable "allows sending a null value for the defined schema", so it should also work outside of properties.

[cziebuhr]

Depending on using swagger 2 / openapi 3, ConnexionOptions sets swagger_ui_local_path to swagger_ui_2_path / swagger_ui_3_path. IMHO this is only the major version of swagger-ui, swagger-ui 3 supports both swagger 2 and openapi 3.