feat: typed request / response schema

[kyujin-cho]

This PR introduces Pydantic based request and response schema validation, along with automatic OpenAPI spec generation of those who've opted in for Pydantic based handler instead of traditional trafaret way.

What's changed

support for Pydantic validator on both request and response body

Now you can pass a Pydantic model, which inherits BaseModel, as a request body validator.

# trafaret way
@auth_required
@server_status_required(READ_ALLOWED)
@check_api_params(
    t.Dict(
        {
            t.Key("traffic_ratio"): t.Float[0:],
        }
    ),
)
async def update_route(request: web.Request, params: Any) -> web.Response:
...

# pydantic way
class UpdateRouteRequestModel(BaseModel):
    traffic_ratio: NonNegativeFloat


@auth_required
@server_status_required(READ_ALLOWED)
@check_api_params(UpdateRouteRequestModel)
async def update_route(request: web.Request, params: UpdateRouteRequestModel) -> web.Response:
...

There are two major advantages of choosing Pydantic in place of of Trafaret: much faster, and native type inference support for params parameter (which will act as a parsed request body). Please note that, after transiting the validator to Pydantic model, you can no longer access values described under request body via string index (params["abc"] way).
Same way also applies for the response schema:

# web.json_response() way
async def scale(request: web.Request, params: Any) -> web.Response:
...
        return web.json_response(
            {"current_route_count": len(endpoint.routings), "target_count": params["to"]}
        )

# trafaret way
async def scale(request: web.Request, params: ScaleRequestModel) -> ScaleResponseModel:
...
        return ScaleResponseModel(
            current_route_count=len(endpoint.routings), target_count=params.to
        )

Note the difference of function return type annotation between two handlers. Explicitly defining the response type will help Backend.AI's automated OpenAPI spec generator understand the response schema and render it as OpenAPI spec.

On-the-fly REST API reference viewer

Two new GET resources (/spec, /spec/spec.json) are newly introduced on this patch.

• GET /spec: returns HTML page containing a REST API reference documentation for Backend.AI. Please keep in mind that this page won't work under the air-gapped environment.
  
• GET /spec/spec.json: returns OpenAPI-3.0.0 compliant JSON schema of whole Backend.AI REST API
  The entire /spec resource is disabled by default, so in order to activate these system administrator has to set value of config/api/allow-openapi-schema-introspection etcd key to yes.

Checklist: (if applicable)

• Milestone metadata specifying the target backport version
• Documentation

[achimnol]

For extra type safety, let's use the pattern matching.

Suggested change

	if isinstance(checker, t.Trafaret):
	checked_params = checker.check(stripped_params)
	else:
	checked_params = checker.model_validate(stripped_params)
	match checker:
	case t.Trafaret():
	checked_params = checker.check(stripped_params)
	case BaseModel():
	checked_params = checker.model_validate(stripped_params)

[achimnol]

I've added a commit to keep consistency of the decorated request handler's typing. The request handler should use Callable[[web.Request, ...], web.StreamResponse] always, so that middleware could be composed in any order and additional strong-typed decorators do not get confused.

Currently I couldn't find a good way to apply typing.overload to embrace both the trafaret version and the pydantic version of check_api_params(), and thus split out check_api_params_v2() for new codes.

Please work on the remaining migration that I've left as TODOs, and also ensure the OpenAPI doc generator's implementation to work with check_api_params_v2().