Update docs to v 1.1 at docs.dataforsyningen.dk
kbevers opened this issue · comments
The current swagger.json doesn't validate because some operations do not have unique IDs (the 1.0 operations and 1.1 operations are identical). This makes it harder to autoconvert to OpenAPI 3.
It might be worth a while to switch to apispec instead, which can generate both version 2 (Swagger) and 3 (OpenAPI).
It might be worth a while to switch to apispec instead, which can generate both version 2 (Swagger) and 3 (OpenAPI).
How does that integrate with flask_restx?
The only other options I see are
- to continue to expose Swagger 2.0, but fix the inconsistencies and still manually convert and tweak at every release
- to improve flask_restx
I suppose 2 is the better option. Do you mind spending an hour or two on estimating how much work is involved in doing that? If it can be done in a reasonable amount of time I think it is worth the effort.
Last release and commit 10 months ago. I think it’s the sure way of getting voted in as maintainer….
Or it is what is needed to reinvigorate the project. The alternative is to completely rewrite WEBPROJ to accomodate a different model for documentation. Choose your medicine :-)
The way I understand it, rewriting flask_restx to support both Swagger 2.0 and OpenAPI 3.0 is also a major effort. But I can look into it, if it is a thing GRF wants done.
To fix the current problem right here and now, I can generate the faulty Swagger 2.0 descriptor, alter the duplicates, convert it using Mermade and make a PR to docs.
Pulled. Now awaiting deployment into production.
Cool. It would be nice to have the procedure described in a HOWTORELEASE file. Do you mind doing that?
I'll look into it.
Also, closing this because the new version has been deployed.