Add support to Specification Extensions

[jairhenrique]

https://swagger.io/specification/#specification-extensions

[tfranzel]

hey @jairhenrique, can you give an example where this would be beneficial? extensions are very generic by nature and could be placed pretty much anywhere.

[jairhenrique]

Hi @tfranzel I want do use this extra data to automate and document some steps on my deployment/environment. This feature will be useful to dev and ops team!

[tfranzel]

i absolutely see the usefulness of this. the problem is that those extensions can in theory be used anywhere in the schema and we have no mechanism to freely place extensions.

how would we try to inject these extensions? @extend_schema? i'm a bit foggy on the details.

[jairhenrique]

@tfranzel I need to take a better look on the source code. I don't know how to make it generic.

Does it make sense to have an object to represent it and some logic in the preprocess hooks?

@extend_schema(
    specification_extensions=OpenApiSpecificationExtensions(
        data={
            'x-foo': 'bar', 
            'x-bar': {'a': 'b'}, 
            'x-node':1 
        }
    )
)

SPECTACULAR_DEFAULTS = {
    "specification_extensions": OpenApiSpecificationExtensions(
        data={
            'x-foo': 'bar', 
            'x-bar': {'a': 'b'}, 
            'x-node':1 
        }
    )
}

[sdabhi23]

We can maybe take the extensions documentation published by Redoc as a starting point and then increase support as required. Some extensions like x-traitTag would go in @extend_schema and others like x-logo can be added to SPECTACULAR_SETTINGS in settings.py

What do you think @tfranzel ??

[tfranzel]

generally i find the idea interesting. but i'm still hesitant on how to cleanly integrate this. as far as i can see those extensions can pop up everywhere and thus code would need to change in a lot of places.

a lot of those redoc extensions are already part of 3.0.3 and are backported for older versions. at least that is what i understand.

sure, extensions like x-logo seem useful and are easy to patch into the info object. i'm more worried about providing a sane way to extensions in all other object types (tag, response, parameter, operation, schema), because some of them are not directly accessible through the provided spectacular decorators.

for small additions there are always postprocessing hooks as a alternative. before really considering this as a core feature, i would like to see some really useful features we are missing out on.

@jairhenrique fyi, we included the examples feature a couple of days ago. some of your points might have also been addressed by OpenApiExample. let me know what you think.

[wattsin]

@sdabhi23 this would be ideal, I realize adding all extensions does not make sense everywhere. But a few key ones in the SPECTACULAR_DEFAULTS defaults could be really useful. Like x-logo

[tfranzel]

so the info section is easy as you said. tags is already covered by a setting. i'll have a look where we have low impact places to add this to. probably not a lot more.

[tfranzel]

as discussed this gives an option for the info object. tags are already covered. due to the generic nature of extensions and the multitude of ways this could be employed, i hardly doubt we can go much further here without doing an incomplete and inconsistent feature.

i'll close the issue for now. if someone can come up with a really good concept here, we can most certainly revisit this.

[allen-munsch]

How to add logo to drf spectacular redoc

🚀🚀🚀🚀

SPECTACULAR_SETTINGS: Dict[str, Any] = {
    'EXTENSIONS_INFO': {
        "x-logo": {
            "url": "https://blahblah.cloudfront.net/static/img/logo-small.png",
            "backgroundColor": "#FFFFFF",
            "altText": "Nice NIce Logo"
        }
    },
}

🚀🚀 Thanks ! 🚀🚀

[tfranzel]

vendors extensions are now supported (#540) with the excellent work of @ngnpope.

[jairhenrique]

vendors extensions are now supported (#540) with the excellent work of @ngnpope.

awesome!