Summary

at the moment the openapi route skeleton uses a dataclass that extends Operation. this is only set'able on the actual route.

@get(..., operation_class=CustomOperation)
Router(..., operation_class=CustomOperation)
Litestar(..., operation_class=CustomOperation)

this proposal is to add the operation_class to each "step" in the chain. by default set Litestar(operation_class=Operation). if the operation_class is set on the Router() then override it for all routes under that router. if its set on the route then override it for the route.

this follows on from #1396

i also think renaming the parameter to something more meaningful might be an option here. maybe something like openapi_output_structure.

Basic Example

from dataclasses import dataclass, field
from typing import Dict, List, Optional

from litestar.openapi.spec import Operation


@dataclass
class CustomOperation(Operation):
    x_scopes: Optional[List[str]] = field(default=None, metadata={"alias": "x-scopes"})
    x_requires_auth: Optional[bool] = field(default=False, metadata={"alias": "x-requires-authentication"})
    
    def __post_init__(self) -> None:
        self.x_scopes = []

@get(..., operation_class=CustomOperation)
Router(..., operation_class=CustomOperation)
Litestar(..., operation_class=CustomOperation)

Drawbacks and Impact

im not convinced this parameter is the most useful of the bunch. you can only specify the class name and the system will then instantiate it with default "extra parameters in the outputed json".

some of the ways that you would be able to even set it would involve middleware / guards / dependencies (anywhere where you get the request object and then set the values. this would probably mean a workaround could be to define opts and then have a function that gets the request look at opts and set it from there.

this would greatly impact setting it on the app level and the router level since then you would again have to define opts on each route then anyways. (but you could probably set a dependency on whichever layer you're on to hard code set it in anycase)

proposal instead is to include an openapi_extensions={} parameter and to handle it all "automaticaly?" with the current structures. again allowing it to be set any any level and the next level overrites the previous all the way to route level.

im not the biggest fan of the "thousand parameters" approach tho. wouldn't it be pertinent then to maybe expose the rendering of the json for the open api spec and let the devs break it however they choose. "after aaaallll the steps and you still want to break it.. you sir.. deserve the pain"

Unresolved questions

1. can the parameter be renamed to something meaningful?
2. is it the most useful parameter out there considering how you have to use some other way to set it / use opts etc
3. aren't there better ways to handle adding openapi extensions