Add DRF spectacular hook(s) to address common linter warnings

[sergei-maertens]

Pretty much all of our projects that generate an Open API spec are linted and produce the same warnings:

There are some options:

• Tweak the spectral ruleset to ignore these warnings
• Add hooks to the shared library that can easily be added to the DRF spectacular settings

If we use the latter approach, I'd say:

• We can generate an empty servers object or something that's domain-agnostic if nothing is present
• We can extract the operation tags and ensure they're collected + added to the global tags

@swrichards @stevenbal @CharString I'm interested in your opinions whether we should provide the hooks here or just tweak the spectral ruleset (which can be done in https://github.com/maykinmedia/open-api-workflows/blob/4383c70a26f3bc5caafd0423bf451ece69bdffe2/actions/oas-lint/action.yml#L62 I suppose)

[swrichards]

Adding these as post-processing hooks sounds sane, certainly for the operations gathering. That seems like a well-formedness issue which we should simply address.

As for the servers key, it seems to me we'd (also) want to enforce that the values are actually configured for the runtime-exposed schema where the base URLs are known (for the static artifact produced for reference having a dummy value is better than no value, but we wouldn't want that to spill over into production instances).

[CharString]

I have been playing around with the vacuum linter (which has spectral and OWASP rulesets).

-z, --hard-mode          Enable all the built-in rules, even the OWASP ones. This is the level to beat!

🙂

There are a lot of rules, some of which can be fixed with spectacular post process hooks.

And this code https://github.com/maykinmedia/open-beheer/blob/122362c387885fae5c0bb80aacfbcdc973b61f5d/backend/src/openbeheer/api/drf_spectacular/schema.py#L279
which I lifted and adapted from django-common, made me think of an API like this:

type Components = Mapping
"A root component schema"

_Schema = TypeVar("_Schema", bound=MutableMapping)
SchemaFix: TypeAlias = Callable[[_Schema, Components], _Schema]

DEFAULT_FIXES: list[SchemaFix] = [
    remove_invalid_url_defaults,
    inline_refs_with_sibblings,
]


def make_spectacular_post_process_hook(fixes: Sequence[SchemaFix] = DEFAULT_FIXES):
    def post_process_hook(result: MutableMapping, *args, **kwargs):
        ... # walk the component tree for sub schemata and apply all fixes

To make it extensible.