Replace `django-rest-swagger` with `drf-spectacular`

[afuetterer]

Rationale / Begründung

django-rest-swagger is deprecated since 2019. Should rdmo switch to an alternative openapi library? drf-spectacular looks promising.

Affected

Software group

References / Verweise

• https://github.com/marcgibbons/django-rest-swagger
• https://github.com/tfranzel/drf-spectacular

[afuetterer]

Using django-rest-swagger

• docs: https://marcgibbons.com/django-rest-swagger/
• Access http://127.0.0.1:8000/api/v1/ -> Swagger UI
• Access http://127.0.0.1:8000/api/v1/?format=openapi -> Swagger JSON (swagger 2.0)

---

Using drf-spectacular

• docs: https://drf-spectacular.readthedocs.io/en/latest/
• https://drf-spectacular.readthedocs.io/en/latest/faq.html#i-get-a-lot-of-warnings
• Access http://127.0.0.1:8000/api/v1/ -> Schema (openapi 3.0.3)
• Access http://127.0.0.1:8000/api/v1/swagger -> Swagger UI
• Access http://127.0.0.1:8000/api/v1/redoc -> Redoc UI
• /manage.py spectacular --color --file schema.yml

[afuetterer]

@jochenklar @MyPyDavid: Do you know, if the swagger UI used or is this just for convenience?

I want to switch out the deprecated library, that generates 100+ warnings when running the tests.

Is it important to generate the exact same UI under the exact same URL?

[jochenklar]

Hi @afuetterer thanks for the effort! No I don't think we need swagger, I never liked it anyway. But I guess we need something like this, meaning a browsable API explorer thingy.

[afuetterer]

Alright, thanks.

drf-spectacular generates the openapi schema in json/yaml and renders those in swagger/redoc.

I will submit a PR, then you can test it.

[afuetterer]

Regarding the versioning here:

There is the RDMO version, e.g. 2.1.3 or 2.2.0, and there is a URL path versioning api/v1/.

What is the difference here?

Is the "version" of the API always "v1"?

[jochenklar]

Yes, the version is always v1, and its there in case we have another one and need to run them both in parallel. A lot of people say that it is super important to version apis in this way, so I try to do it all the time. An I needed it once.

[afuetterer]

$ python manage.py spectacular --color --file schema.yml --validate
[...]
Schema generation summary:
Warnings: 237 (109 unique)
Errors:   28 (5 unique)

[afuetterer]

This is the swagger schema generated by django-rest-swagger: https://github.com/afuetterer/rdmo/blob/698-drf-spectacular/django-rest-swagger.yaml

npx open-swagger-ui --open django-rest-swagger.yaml

[afuetterer]

What about this repo?

https://github.com/rdmorganiser/rdmo-openapi