-
-
Notifications
You must be signed in to change notification settings - Fork 1.2k
Implement Dynamic OpenAPI Generation with. OAS 3.0 Support #15729
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
Conversation
It doesn't work properly in any of the apps and tools when paths are off.
This is what determines the file name when downloading, and a single quote in a file name is always a source of trouble.
I've taken the default 3.1 version, the 3.0 version and a 3.0 Light version and ran it through several OpenApui validation tools (swagger-cli, Redocly CLI, Prance and openapi‑spec‑validator or similar) npx ajv-cli validate --spec=draft2020 -s openapi-3.1.0-schema.json -d '/mnt/c/Users/admin/Downloads/Weblate_3.1_invalid.yaml' --strict=false All passed - Redocly CLI showed a number of warnings only. |
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## main #15729 +/- ##
==========================================
- Coverage 91.36% 91.27% -0.09%
==========================================
Files 645 646 +1
Lines 67307 67510 +203
Branches 6930 6992 +62
==========================================
+ Hits 61492 61623 +131
- Misses 4068 4112 +44
- Partials 1747 1775 +28
🚀 New features to boost your workflow:
|
Spectacular should be able to create a 3.0 schema directly without needing to maintain the conversion code. Unfortunately, it seems to be settings only ( |
There is no conversion code. I'´m setting The code that is there has different purposes: _filter_patterns()That's the provided way by SpectacularAPIView for filtering out certain paths. I'm pretending to do this "by Tags", while in reality, paths are filtered by the first path segment. But as this is always the same as the tag, it's essentially that: "filter by tag" _prune_unused_tagsWhile the above is filtering out the paths, it doesn't filter out the actual Tag elements. _prune_unused_components()The next problem is that when we filter by using the patterns parameter, sperctacular omits the compoinent schemas from the directly related definitions, but it still leaves most of it in the document. _collect_used_security_schemes()The only purpose of this function is to identify the security_scheme items, because they would otherwise be cleaned up by _strip_examples()Does what it says for data examples. Note: The code for stripping out the errors (when chosen) is still inline, it should probably be moved out for consistency. Both of the latter play together with _prune_unused_components(). They are removing the directly related elements and |
This means in turn: For a URL like |
Thanks for the explanation. I really didn't look at the patch as it's really hard to review because of moving code to another file and then adding new code instead of it - the diff is really messy. Having the fixes separate from the new feature would make it much easier to review. I will get to reviewing the patch, but probably not before the 5.13 release. If you can split it up, the fixes will be easier to review and can be processed sooner. |
Have you seen that there are 9 separate commits, each one doing a very specific change only? |
The second commit (a2c3e57) moves the configuration without making an actual change to the contents, so that content changes can be reviewed properly. (you just need to review commit-by-commit) |
If you prefer the drf settings code to remain in the spectacular.py file, I can reshape the PR. The original reason for moving it was that I had encountered once another circular referencing problem, but I think it resolved naturally, later. I still found it reasonable to keep it separate, though, but there are many valid way for structuring things and I'm good with whichever way you like. |
Last week, I wanted to generate a .NET ApiClient library for weblate in order to automate a few things.
We're auto-buiilding REST client for a range of languages/platforms, so that they're always up-to-date, so I didn't expect any problems in doing so.
Until I realized that Weblate OpenAPI description are using spec 3.1. That's a problem, because almost nobody is ready for that yet, even some are claiming to be, B
ut when you look closer, you'll realize that an OAD according to OAS 3.1 is largely useless at the time of writing. Most of the tools and tooling hasn't been updated yet, and those who really support 3.1 are entirely new developments - but for 3.1, and they typically do not properly work for 3.0.
That little minor bump is not as minor as it might appear to be. at first sight.
3.1 is an update with a small set of extremely incompatible changes.
It took me several hours and multiple tools to convert the 3.1 from Weblate to a 3.0 version which - most importantly - is actually accepted by 3.0 tools.
Also, the generated document is highly bloated by tons of error response models, spec extensions and inefficiently build component schema. This week, I wanted to try leeting some AI interact with the Weblate API, but those 2MB are way outside of what they are able to ingest.
The latter is the reason for the comprehensive filtering capability: being able to get openapi descriptions creaed in a compact and efficient way.
3.0 doesn't support Webhook descriptions, so I kept 3.1 as the defauilt.
While at it, I also added a Swagger view because ReDoc doesn't have a "Try out" featue.
Finally, the base path was wrong - which had caused all tool and consumers to failing out-of-the-box behavior.
Other changes:
/api/schema/?params...
) is included in the API doc itselff nowwhich also determines the file name when downloading
This is hwo it looks with those changes applied: