Add support for multiple implementations in operationId about connexion HOT 11 CLOSED

According to Swagger Spec operationId has to be a string.

Connexion supports Jinja2 templating and Selmer for Clojure seems similar, so maybe it's possible to change the operationId based on the implementation:

operationId: {% if using_connexion %}app.get_users{% else %}get_users{% endif %}

from connexion.

how a JSON or YAML is not string? :D

from connexion.

The templated version looks really horrible.

operationId: '{"connexion": "app.get_users", "swagger1st": "get_users"}' 

though it is not quite clear, if this version with JSON as a string is better :)

from connexion.

@jmcs is right, "operationId" must be a single string.

We could implement some name mangling, i.e. using one operationId for both Connexion and Swagger1st and automatically finding the correct function:

• Connexion could use a configurable base module to prepend
• Swagger1st could use a configurable base namespace to prepend and additionally replace underscores with hyphens

from connexion.

Small introduction how the operationId is handled in https://github.com/sarnowski/swagger1st :

The configured executor has a generic way of plugging in any operationId evaluation you need. The default implementation resolves the operationId string to a full qualified Clojure function.

However, this can be configured as you like. The resolver takes a function that takes the argument operationId (actually the whole request definition) and returns a function that should be called upon request. This generic functional approach allows you to plug in every logic you might want. Some examples:

(s1st/executor
  :resolver (fn [request-definition]
               (let [operationId (get request-definition "operationId")]
                 (function-by-name operationId))))

You can also think of completely different implementations like a SQL executor:

(s1st/executor
  :resolver (fn [request-definition]
               (let [sql-query (get request-definition "operationId")]
                 (fn [request]
                   (jdbc/execture sql-query)))))

For this issue, there are only 2 clean ways in my opinion:

Way 1: Abstract Idenfitier

The Swagger Spec also specifies the operationId as an identifier for the operation. There is no specification that this has to translate to a language specific construct. One way to tackle the language-independent integration is to make this identifier compeltely abstract and let the implementations resolve it.

operationId: "foo"

Using a mapping table in the implementation, one is able to determine the correct action. Luckily, Clojure's map is also a function, so a map can directly be used as a resolver in swagger1st:

(s1st/executor
  :resolver {"foo" api/my-foo-fn
             "bar" api/my-bar-fn})

I consider this the cleanest solution as it makes no assumption at all about the implementation.

Way 2: Declarative Configuration

If you really want to encapsulate implementation specific information per implementation, then I would go for embedded JSON as a declarative way:

operationId: '{"connexion": "my-py-fn", "swagger1st": "my-clj-fn"}'

This way, it is trivial for any implementation to get to is implementation specific value by just parsing JSON (which is the easiest format in any language):

(s1st/executor
  :resolver (fn [request-definition]
               (let [operationId (get request-definition "operationId")
                     s1st-operationId (-> operationId json/parse :swagger1st)
                 (function-by-name s1st-operationId))))

I would discourage any idea of trying to use a turing complete templating engine to "generate" a correct string!

from connexion.

As I understand, way2 can be considered as one of the default implementations of the way1.

from connexion.

I'm completely against having way 2 as default on connexion, not only it's hacky, it would also break existing code. Adding support for a custom mapper seems cleaner.

from connexion.

@valgog in case of swagger1st, this would be a custom handler anyway yes

from connexion.

@jmcs one should not really break anything, one could implement the resolver with a fallback possibility.

Anyway, even if we would decide to go with the Way2, we have to have a solution for the Way1 in connexion. Do we have it already?

from connexion.

@valgog no, not yet, I would propose adding some "operation resolver" configuration to the Api class (default implementation like it is now).

from connexion.

@hjacobs I agree, I will assign this issue to my self to implement this approach.

from connexion.