Register pyramid views/routes automatically from swagger spec

[striglia]

#128 discusses exposing data on the endpoints represented in the Swagger spec.

In addition, some users may want to avoid having to manually register each of these into Pyramid. We could use the unique operationIDs as route_names in Pyramid, and register them automatically. The user would then just need to add a new function and decorate it with @view_config, setting route_name to the same operationID for it to magically be registered together.

[dnephin]

The 2.0 spec allows for "extensions", where you can create your own fields with a x- prefix. It would be cool to support an x-pyramid-route extension, which would let you put the route name for an operation right into the spec.

That would make it really easy for pyramid_swagger to generate all the routes directly from the spec.

Maybe this is unnecessary though, and a convention could be used without having to name the route yourself.

[striglia]

Yeah, the extensions are really really exciting.

The main upside I can think of is we get to define the format and enforce invariants if we make a new extension. Making some loose convention like "we're going to name routes by the nickname of the swagger operation" feels like a dangerous direction...

[johnschultz]

I talked some with @striglia about this a few days ago. If we are going to allow routes to be defined in the swagger, it would be nice to also be able to define other pyramid related things in the swagger as well (possibly using extensions as @dnephin said). For example, validators or route/view predicates could be defined in swagger and automatically passed to add_route and view_config. Thoughts?

[dnephin]

I think that would be ok as long as those things are related to the interface or swagger in some way. I like the idea of specifying routes because operation -> route is basically always going to be a 1-to-1 mapping and doing it in the swagger spec reduces a bit of boilerplate. I guess if the add_route() was being done automatically then it would make sense to include route predicates as well (some could actually be implied from the spec already, like http_method).

I think there is a danger of including too much in the spec, I'm not sure which view predicates would be relevant. The mapping of which view handles which route would still be in the python code (most likely in the view_config decorator, so it might make sense to keep the view predicates there.

[striglia]

I do wonder if there's any mechanism in pyramid to defer all customization. If we agree on a route name, and pyramid_swagger registers a view for that route, can you then post-customize it at all? Are there any other examples of registering routes but delegating customization we can reference here?

Agreed that (in general) we want to minimize what we add to the Swagger schema, particularly extensions. I think explicitly calling out a route name will be inevitable (and have various other benefits) but I'd like to try hard to avoid expanding it further if we can solve these issues elegantly out of band.

[johnschultz]

http://docs.pylonsproject.org/docs/pyramid/en/latest/narr/introspector.html

Pyramid has it's introspection system, but I find it very, very hard to use. I'm not sure we can use it to actually edit the configuration though.

[sabrina261087]

Hello, I tried to create a pyramid project using the following tutorial: http://docs.pylonsproject.org/docs/pyramid/en/latest/narr/project.html Then I wanted to integrate pyramid_swagger using the following link http://pyramid-swagger.readthedocs.org/en/latest/configuration.html

I always got errors

[dnephin]

Hello Sabrina, This is the wrong place to report errors. Could you open a new issue with more detail about the errors you encountered?

[sabrina261087]

hello , ok sorry :)

[striglia]

@tomster

To start you off:

• We've done some registration in api.py already. Would be easy to add more there :)
• You'll likely hook into the tween's includeme around here
• You will find most of our logic for actually validating a request from here on. Let's not be afraid to have this only work for Swagger 2.0 (it will make much simpler) and we can just document appropriately.

That should be a good start but let me know if I can give more context :)

[tomster]

i have been discussing this with @striglia today here at europython 2016 and we're settling on the following approach:

• we will restrict the mechanism to only register the route, nothing else (i.e. deferring all view configuration to the view authors, i.e. via @view_config (another nice example IMHO how pyramid's insistence on keeping those two separate :-)
• we can use the operationId as route name, as the specification requires it to be globally unique
• we could make auto-registration optional, as to not break backwards compatibility