OpenAPI 3 docs not showing example values

[quirinziessler]

When looking at the Swagger (OpenAPI 3) docs, I noticed that for a bunch of api calls the example and also acceptable values are missing and just "string" is shown.
The issue is showing up on v2.28.0 and on the latest dev version. Versions between may also be affected.

Below some examples:

[macsoun]

same thing on v2.31.1

[Stamka]

all the same v2.28.3

[manuel-sommer]

@kiblik do you have any idea on this?

[kiblik]

Short answer

no idea

Long answer

None of the Dojo models specify examples in schemas (as it is officially documented) right now.
It is used only in Paginated OpenAPI definitions (usually GET without ID). I suppose it is added by a standard rendering mechanism.

So I expected that if you can see some examples (e.g. credentials), they are generated by swagger-ui based on a definition of a schema.

I thought that they were not generated in some cases (e.g. engagements) because of some less standard schemas (e.g. mix arrays of strings and nulls - engagement_type).
However the same is happening in more standard but customized scenarios (e.g. I excluded ['date', 'mitigated_by'] from EndpointStatusSerializer so it used only booleans and integers but it was still failing).

So to be honest, I do not know.

[Maffooch]

@kiblik When I set the swagger UI to use def-spectacular-sidecar (set in #9118) I have useful example schemas and and response bodies again. I am not sure if this is a complete solution, but I have eyeballed each endpoint and everything looks alright. Here is all I did:

# If true, drf-spectacular will load CSS & JS from default CDN, otherwise from static resources
DD_DEFAULT_SWAGGER_UI=(bool, False), # Changed from True -> False

I'd be happy to throw up a PR flipping the default if there is consensus that this a good way forward

[kiblik]

Ok. Thank you @Maffooch. Now I see what is happening.

At first, all versions of DD are automatically (if you do not set DD_DEFAULT_SWAGGER_UI=False) using latest swagger pulled from public CDN.

Analysis about DD_DEFAULT_SWAGGER_UI=False

Latest DDs (2.31.0..2.31.4) are using drf-spectacular-sidecar in version 2024.2.1

django-DefectDojo/requirements.txt

Line 77 in c5d896b

drf-spectacular-sidecar==2024.2.1

Which contains swagger-ui-dist in version 5.11.2

https://github.com/tfranzel/drf-spectacular-sidecar/blob/a383edc500b370c00e521efc8b17e6267234f3fd/distributions.json#L3

I expect that new version of drf-spectacular-sidecar will be automatically released of March 1st as version 2024.3.1 with swagger-ui-dist in version 5.11.8 or 5.11.9

Version 5.11.2 works fine (in the context of this issue, I have no knowledge of the rest of this tool).

Analysis about DD_DEFAULT_SWAGGER_UI=True (default config)

I came through recently released versions (you can do it by yourself by adding SPECTACULAR_SETTINGS['SWAGGER_UI_DIST'] = 'https://cdn.jsdelivr.net/npm/swagger-ui-dist@5.11.8' to settings.py). I found out that 5.11.7 works well and 5.11.8 (version released 5 days ago) is showing "string" instead of the definition as json.

Next steps/workaround

• Using DD_DEFAULT_SWAGGER_UI=False will help to fix urgent problems. But it is not a long-term solution.
• (edit) I propose to open an issue in https://github.com/swagger-api/swagger-ui/issues (there is not this kind of issue from the last 5 days). Issues already is already open Swagger Docs for dcm4chee-arc only shows subsets of APIs swagger-api/swagger-ui#9645
• For DD moderators: If the new version of drf-spectacular-sidecar will be released (it might be soon and it might be offered by dependabot) with swagger-ui-dist in version 5.11.8, I recommend not merging it (for now) because it would break instances for everybody who uses DD_DEFAULT_SWAGGER_UI=False

[Maffooch]

Excellent analysis! I agree with what you have proposed here. I will keep my eyes open for sidecar updates coming from dependably/renovate

I thought I was going crazy for a minute there because I was so confident #9108 was good to go when it was merged 😅

[kiblik]

(edit) I propose to open an issue in https://github.com/swagger-api/swagger-ui/issues (there is not this kind of issue from the last 5 days). Issues already is already open swagger-api/swagger-ui#9645

[kiblik]

Good news everyone: swagger-api/swagger-ui#9645

[kiblik]

⚠️ my concerns become true: drf-spectacular-sidecar was released in version 2024.3.1 with broken swagger-ui-dist in version 5.11.8.
I recommend, not merging mentioned version otherwise DD_DEFAULT_SWAGGER_UI=False will have an "opposite" outcome.

But still, we can ask to release an earlier version of drf-spectacular-sidecar only because of this fix.