init spectree with plugin instead of name, use body instead of json

[kemingy]

To keep the interface clean and flexible, it's better to pass the plugin class instead of backend framework name strings. Also, the sync/async flag should be written to the plugin class as described in https://github.com/0b01001001/spectree/pull/46/files#diff-485ad20a22f45089777317b26137dc90R13-R15

Since the body can be serialized in multiple ways, like JSON, MessagePack, ProtoBuf, etc. Although JSON should be the most common way to do so, it's better to support other methods.

[kemingy]

Considering 99% use-cases are JSON API

That's True.

To support multiple serialization methods, it may require the user to define their own handlers. Currently, it works fine for most of the use cases.

The interface may look like:

handler = HTTP_body_handler(
    content_type='application/json',
    serialize=json.dumps,
    deserialize=json.loads
)

# global default handler
api = SpecTree(handler=handler)

# endpoint handler
@api.validate(handler=handler)

[yoursvivek]

I had some thought about these issues, while making changes for #100. I'm jotting them down.

1. body and payload are two well known identifiers for what's currently called json. Renaming will clean up the function signature of any naming convention bias towards one [de]serialization method. json commonly refers to json built-in module or one of many drop-in json module replacements.

2. While implementing enable view function annotation based type detection #100, I did end up creating a variable named json in the current namespace which refers to validated pydantic model for http body. And therefore, if json module was imported, it will be masked inside view function.

3. It can be implemented with breaking changes deferred to later release as follows:
   a. Let validate function accept another keyword (preferably keyword only?) argument called body.
   b. As the very beginning of validate, check presence of json and body. Allow only one of them to be present or give one precedence over the other and log a warning message. Issue a deprecation warning informing that json parameter will be dropped after a particular release.
   c. Thereafter, in all internal code for spectree use body instead of json

4. Since there will be one breaking change in validate, it will be prudent to consider making all arguments of validate keyword once, this is make it easier to add features at a later date. This is important because validate function is playing multiple roles viz validating data models (akin to webargs) and collecting model types for registry into openapi spec schema components. In future with addition of other de/serialization implementations, other requirements might pop up.

5. On using handlers, I think spectree should accept any subclass of a base handler object with trait like:

class BaseHandler:
   def serialize(self, **kwargs):
        ...
   def deserialize(self, **kwargs):
        ...

6. Handling multiple content type should also be an option and de/serialize functions can absorb the complexity of de/serialization for different protocols. Even in the realm of json only apis, multiple content-types can be in use like in vendor ct. Github allows all of the following for it's json api implementation.:

application/json
application/vnd.github+json
application/vnd.github.v3+json
application/vnd.github.v3+json
application/vnd.github.v3.raw+json
application/vnd.github.v3.html+json
application/vnd.github.v3.text+json
application/vnd.github.v3.full+json
# etc ...

c.f.: https://docs.github.com/en/free-pro-team@latest/rest/overview/media-types

[kemingy]

I think we can standardize all these keywords now.

• json -> body

Singular or Plural?

• header or headers
• cookie or cookies
• query or queries

For the handlers, users may have multiple kind of content types. For example, multipart/form-data, x-www-form-urlencoded, application/json. So it should be a <content-type: Handler> dictionary?

For the breaking changes, we can add use semantic versioning. Old keywords will be warned in v1 and will be dropped in v2.

[yoursvivek]

All of them seem good to me.

1. body
2. Plurals.
3. <content-type: Handler>
4. Semvar for deprecating old keywords.

[alexted]

• headers
• cookies
• query (or mb query_params, query_args)

[ula]

I understand that these changes require more thought and lots of breaking changes but is there a timeline for these changes? thanks

[kemingy]

I understand that these changes require more thought and lots of breaking changes but is there a timeline for these changes? thanks

@ula Actually, there is no timeline for this. I'm too busy these days. BTW, I will try to avoid the breaking by making the default behavior acts as it is now. I don't have a very clean solution now. Feel free to comment here if you have any suggestions.

[gomeslucasm]

Any updates about it?
I've made some comments in an issue, but now I found this thread.
#85

[and3rson]

Same here - I'm trying to consume raw XML body from the request. Any updates on this?

[kemingy]

You can check the pydantic GetterDict.

[and3rson]

@kemingy Are there any examples? It seems like spectree's starlette plugin always tries to parse the request as either JSON or form:

# spectree/plugins/starlette_plugin.py:65
        request.context = Context(
            query.parse_obj(request.query_params) if query else None,
            json.parse_obj(await request.json() or {}) if use_json else None,
            form.parse_obj(await request.form() or {}) if use_form else None,
            headers.parse_obj(request.headers) if headers else None,
            cookies.parse_obj(request.cookies) if cookies else None,
        )

This means there's no way for spectree to allow raw request body that's neither JSON nor form.

A workaround is to simply not provide any request schema (json/form kwargs) and parse request directly with await request.body(), however this makes it impossible to send data through Swagger, since the schema does not include any body parameters.

[kemingy]

Will it work if we change it to the following?

json.parse_raw(await request.body() or '') if use_json else None,