Support for OpenAPI parameter serialization

[adriangb]

Does BlackSheep support for OpenAPI parameter serialization (aside from the defaults)?

[RobertoPrevato]

Hi @adriangb
No, currently only defaults are supported. And thank you for bringing this up, this would be an interesting feature. It is possible to define custom binders, so it's open to such extensions, but the interesting point would be to include also the generation of OpenAPI Documentation.

[adriangb]

awesome. I agree that having two different binders makes sense, and I like your strategy for backwards compatibility.

With respect to using binders for documentation, I agree with you that it is better to keep things to having a single responsibility. However, I have a couple counterpoints. These are questions I am legitimately unsure of, and I'm curious what you think, if you have the time to answer 😃

1. The options mentioned are not just for documentation. They determine how the values are extracted from the request (I guess that is binding in BlackSheep terminology)
2. They are already influencing the OpenAPI documentation
3. What is the alternative? Using seperate markers (in type annotations like BlackSheep or default values like FastAPI)?

[RobertoPrevato]

In cases like this one, I think respecting the single responsibility principle is a requisite. Imagine if I made the Binders (currently they only care about extracting a value from a web request) care also about their representation in the current version of OpenAPI Documentation: v3. What if somebody wants to support v2? What when there will be OpenAPI Documentation v4? Will everything happen in the same classes?

There are ways to keep things decoupled so that supporting a older version of OAD or a newer won't require touching the classes that are already doing something important.

Just my opinion, after all there are thousands of different opinions when it comes to programming, so I like to have some myself. 🙂

[adriangb]

I generally agree with your opinion, does that mean it is not yours anymore 😛?

Just to clarify though, would you say that the binders currently adhere to the single responsibility principle? It sounds like they are used to generate the docs, even if they themselves are not aware of the OpenAPI at all.

For my toy project, I was thinking of doing something like:

def endpoint(value: Annotated[int, ExtractFromQuery(style="deepObject"), OpenAPIv3QueryParam(style="deepObject")]):    ...

Only problem is that this is super verbose! As far as I can tell, there is no way to "compose" these things into some sane default (like def endpoint(value: FromQuery(style="deepObject")), which would be ideal) due to limitations of (1) annotations not supporting () syntax directly and (2) python/typing#779

[RobertoPrevato]

Yes, in my mind binders today have a single responsibility, and I think this is proven by the fact that the base abstract class Binder defines a single abstract method get_value that sub-classes must provide.

When it comes to your example, I would recommend to not try to make a generic API for rare scenarios. What I mean is: most of times query strings are used to handle scalar values or arrays (much more often scalar values than arrays, by the way -like "response_mode=form_post"). If the user of the framework has specific needs, enable defining a custom class to bind incoming values.

In my case, this is supported in blacksheep defining a custom binder - which is by the way the same approach found in ASP.NET Core.

[RobertoPrevato]

By the way, I was planning to add more extensibility points to the current logic that generates OpenAPI Documentation v3, to make it easier to modify the documentation generated for specific parameters / endpoints. I didn't yet simply because time is limited.