Sourced*

Frameworks

Generate an SDK from Django REST Framework with drf-spectacular

· 6 min read · Sourced

  • django
  • drf
  • python
  • openapi
  • sdk

Django REST Framework has no OpenAPI output of its own — the widely-used way to get one is drf-spectacular, a third-party package that introspects your serializers and views and produces a real OpenAPI 3 schema. Once that schema exists, turning it into a TypeScript or Python SDK is the same next step as any other framework: run it through a generator, or a hosted pipeline like Sourced that adds hosted docs and SDK previews in the same pass.

Setting up drf-spectacular

Install it:

pip install drf-spectacular

Register it and point DRF's schema generation at it in settings.py:

INSTALLED_APPS = [
    # ...your other apps
    'drf_spectacular',
]

REST_FRAMEWORK = {
    # ...your other settings
    'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema',
}

drf-spectacular's own documentation notes that the defaults "should work reasonably well out of the box," but recommends setting real metadata for anything beyond a quick test:

SPECTACULAR_SETTINGS = {
    'TITLE': 'Your Project API',
    'DESCRIPTION': 'Your project description',
    'VERSION': '1.0.0',
    'SERVE_INCLUDE_SCHEMA': False,
}

SERVE_INCLUDE_SCHEMA: False keeps the schema endpoint itself out of the generated schema's own path list — a small but common cleanup.

Wiring up the schema and docs UI routes

Add three routes to urls.py — one for the raw spec, two for interactive UIs:

from drf_spectacular.views import (
    SpectacularAPIView,
    SpectacularSwaggerView,
    SpectacularRedocView,
)
from django.urls import path

urlpatterns = [
    path('api/schema/', SpectacularAPIView.as_view(), name='schema'),
    path('api/schema/swagger-ui/',
         SpectacularSwaggerView.as_view(url_name='schema'),
         name='swagger-ui'),
    path('api/schema/redoc/',
         SpectacularRedocView.as_view(url_name='schema'),
         name='redoc'),
]

SpectacularAPIView is the one that matters for SDK generation — it's the route that serves the raw OpenAPI YAML/JSON. The two view classes below it both point back at that same route via url_name='schema', so the UIs and the raw file never drift out of sync with each other; they render the same document.

The gotcha: auto-named enums collide

drf-spectacular derives a name for every enum it emits — typically from the field name or the component it belongs to. That naming can collide in a way drf-spectacular's own FAQ documents directly: when two different fields resolve to the same set of choice values (their FAQ example is payment_currency and preferred_currency both referencing an identical currency list), or when two enum fields share a name but have different value sets, the postprocessing step appends a suffix to disambiguate them.

That's the same root problem covered in fixing inline schema names like Type1 and InlineObject: something in your API has no unambiguous name of its own, so the tooling invents one — and the invented name is rarely one you'd choose or want a customer reading in their SDK's type definitions. drf-spectacular's documented fix is the ENUM_NAME_OVERRIDES setting, which lets you map a specific set of choice values to the exact name you want, supporting Django's models.Choices and plain Python Enum classes as sources.

SPECTACULAR_SETTINGS = {
    # ...
    'ENUM_NAME_OVERRIDES': {
        'PaymentCurrencyEnum': 'myapp.models.Currency.choices',
    },
}

If your generated SDK has type names like PaymentCurrencyEnum next to PaymentCurrencyEnum1, this setting — not a spec fix — is the resolution. It's also worth auditing your serializers for operationId-worthy names: DRF viewsets and generic views get sensible defaults from the view and action names, but two views that resolve to the same derived name are a real, documentable risk in a large API — the fix pattern is the same one described in fixing missing operationId errors.

From a Django spec to hosted docs and typed SDKs

Once your enum names are stable, turning the spec into an installable SDK is a separate step — with docs and SDK previews together, it's the shortest path from OpenAPI spec to live docs and SDK previews. With Sourced:

  1. Connect your repo or point at the schema URL. Connect from GitHub, or paste the api/schema/ output directly.
  2. Preview the Python and TypeScript SDKs. Sourced renders both, including the resolved enum and model names, before anything publishes.
  3. Get hosted docs and an llms.txt from the same pass. No separate docs deploy for a DRF app that doesn't already have one.
  4. Publish when the preview is clean. Free unlimited previews and up to 2 hosted noindex docs review sites and one hosted MCP server, no credit card required.

Comparison: drf-spectacular vs. a full SDK pipeline

Need drf-spectacular gives you What it doesn't give you
A generated OpenAPI 3 spec Yes, via AutoSchema introspection Nothing — this part is real and free
Interactive API browsing Swagger UI and ReDoc routes A hosted docs site for customers
Stable enum and model names Yes, with ENUM_NAME_OVERRIDES set Not by default on a collision
A typed Python client for other services Nothing built in Generated Python SDK
A typed TypeScript client for frontend consumers Nothing built in Generated TypeScript SDK
A diff before a breaking release Nothing built in A compatibility report

OSS generators for other languages

Sourced's generated SDKs focus on Python and TypeScript today — the two ecosystems where teams publish first, and exactly the pairing a Django API (Python backend, TypeScript frontend) usually needs. For anything further out, a DRF spec via drf-spectacular is a standard OpenAPI 3 document, so it works with the usual per-language generators — Go, Java, Ruby, PHP, C#, Kotlin, Rust, and Swift each have a dedicated walkthrough. The five-minute generate-an-SDK guide covers the generic local-generator path.

Honest scope: when DRF's own tools are enough

If your DRF API is consumed only by other internal Python services, DRF's browsable API plus a shared requests-based client function is often genuinely sufficient — you're not paying for schema drift risk across languages you don't have. drf-spectacular earns its place the moment you need a real spec for a validator, a docs site, or any non-Python consumer, even before you generate a full SDK. Reach for a full SDK pipeline once you have external customers, multiple target languages, or a docs site that needs its own domain and version history independent of your Django deploy.

FAQ

Does Django REST Framework generate OpenAPI automatically?

No. DRF ships a basic schema generator, but the practical standard for a real OpenAPI 3 document is the third-party drf-spectacular package — set DEFAULT_SCHEMA_CLASS to its AutoSchema and it introspects your existing serializers and views.

What's the difference between SpectacularAPIView and SpectacularSwaggerView?

SpectacularAPIView serves the raw OpenAPI document (YAML or JSON) — that's the file you feed to an SDK generator. SpectacularSwaggerView and SpectacularRedocView render interactive docs UIs that read from that same view via url_name, so they always match what SpectacularAPIView serves.

Why do I have duplicate enum names like PaymentCurrencyEnum1 in my generated SDK?

drf-spectacular names enums from field or component names, and two different fields that happen to reference the same set of choices — or two fields with the same name but different choices — produce a naming collision that gets resolved with an appended suffix. Fix it with the ENUM_NAME_OVERRIDES setting in SPECTACULAR_SETTINGS.

Does drf-spectacular support OpenAPI 3.1?

Check your installed version's release notes before assuming — OpenAPI version support has evolved across drf-spectacular releases. Validate the actual emitted document rather than assuming; see OpenAPI 3.1 vs 3.0 for what changes between versions and how to convert if needed.

Can I generate the OpenAPI spec without a running server?

Yes — drf-spectacular ships a manage.py spectacular management command that writes the schema to a file directly from your Django project, without needing a live server request against SpectacularAPIView.

Do I need drf-spectacular if I'm only using Django's admin and templates, not DRF?

No. drf-spectacular is specifically for Django REST Framework's serializer- and viewset-based APIs. If you're not using DRF, there's no OpenAPI schema to generate from Django's admin or template views — they aren't a JSON API in the first place.

Ship it

Once your DRF spec has stable enum and operation names, start free on Sourced to preview a Python and TypeScript SDK plus hosted docs from it in one pass, or run the schema through the OpenAPI validator first to catch naming collisions before you generate anything.