Add OpenAPI 3 spec with Swagger UI and ReDoc by adobloug · Pull Request #4095 · Uninett/nav

adobloug · 2026-06-18T09:06:39Z

Summary

Adds an auto-generated OpenAPI 3 specification for the NAV REST API, generated with drf-spectacular, with interactive documentation browsers:

/api/schema/ — raw OpenAPI schema
/api/schema/swagger-ui/ — Swagger UI
/api/schema/redoc/ — ReDoc

Details

Views and serializers are annotated so manually-handled query parameters, responses and authentication schemes are reflected in the schema.
A preprocessing hook keeps only the versioned /api/<version>/ endpoints, de-duplicating the double mount (/api/ + /api/<version>/) and excluding internal app APIs.
Custom token auth and JWT auth are registered as OpenAPI security schemes.
A generated snapshot is committed at doc/api/openapi.yml and kept in sync by a CI check (tox -e openapi-schema) that regenerates the schema and fails on drift. The spec version is normalized to the plain release version so the snapshot is reproducible across builds.

Why both Swagger UI and ReDoc?

drf-spectacular ships ready-made views for both, and they serve different audiences from the same generated schema, so exposing both is essentially free.

ReDoc (open source, maintained by Redocly) is a documentation renderer rather than an interactive console. Where Swagger UI centers on a "Try it out" request console, ReDoc focuses on readable reference documentation:

Three-panel responsive layout — navigation sidebar, prose documentation in the middle, and request/response examples plus payload samples on the right.
Reference-oriented, read-only — no live request execution by default, which makes it well suited for browsing, sharing and linking to API docs without a running/authenticated session.
Deep schema rendering — handles nested objects, $ref components and large schemas (like the de-duplicated NAV one) with expandable, deep-linkable sections.
Single self-contained page — easy to point external integrators at.

In short: Swagger UI for poking at endpoints interactively, ReDoc for reading and sharing the API reference. Both are generated from the same committed openapi.yml, so they never drift from each other.

Testing

tox -e openapi-schema (snapshot up to date)
ruff format/ruff check clean on changed files
New integration tests assert the schema endpoints return 200 and the schema contains only versioned paths

Closes #4094

Checklist

🤖 Generated with Claude Code

hmpf

We're familiar with drf-spectacular and swagger-ui, could you write a bit about ReDoc in the PR?

adobloug · 2026-06-29T05:42:08Z

Added a "Why both Swagger UI and ReDoc?" section to the PR description. Short version: ReDoc (open source, by Redocly) is a read-only reference renderer with a three-panel responsive layout (nav / docs / examples), good for browsing and sharing API docs without a running session, while Swagger UI is the interactive "Try it out" console. Both render from the same committed openapi.yml, so they stay in sync.

lunkwill42

I'd simply say this supersedes my old attempt at the same in #3380 - I couldn't get anyone to review that unfinished piece of crap, and so it was forgotten.

I'll have a closer look at this, but probably not until August, when I can do it together with @hmpf

lunkwill42

Actually, I will drop a single RFC before we get to a full content review: IMNSHO, this tries to do too much in a single commit. I would prefer to see this broken down into a series of logically sequenced commits of smaller scope (where the commit log can actually explain why the individual parts are there). That would make it easier to review, and also easier to do a git blame on further down the line.

codecov · 2026-07-09T10:38:49Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 65.40%. Comparing base (dc68ca0) to head (212bc9c).

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #4095      +/-   ##
==========================================
+ Coverage   65.39%   65.40%   +0.01%     
==========================================
  Files         629      631       +2     
  Lines       47191    47231      +40     
==========================================
+ Hits        30859    30890      +31     
- Misses      16332    16341       +9

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

adobloug · 2026-07-09T10:56:03Z

Thanks for the RFC — agreed. I've split the single commit into eight logically sequenced, smaller-scope commits, each with a message explaining why that part exists:

Add drf-spectacular dependency
Enable OpenAPI schema generation
Register API auth schemes in the schema
Annotate API views and serializers for the schema
Serve the API schema, Swagger UI and ReDoc
Commit generated OpenAPI schema snapshot
Keep the OpenAPI snapshot in sync via CI
Document the API schema and add changelog

The resulting tree is identical to the previous single commit. No rush on the full content review — happy to wait until August so you and @hmpf can go through it together.

drf-spectacular generates an OpenAPI 3 schema from Django REST Framework views. Add it as a runtime dependency; later commits wire it up to produce and serve NAV's API schema. Ref Uninett#4094 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Register drf_spectacular, set it as DRF's default schema class and add SPECTACULAR_SETTINGS with the API title, description and version. NAV mounts the latest API version at both /api/ and /api/<version>/, and some apps expose internal-only APIs. Add a preprocessing hook that keeps only /api/<version>/ endpoints, de-duplicating the double mount and dropping internal APIs from the public schema. Ref Uninett#4094 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

drf-spectacular cannot introspect NAV's custom token authentication or the JWT authentication from oidc_auth. Add extension classes so both appear as security schemes in the generated schema. Importing the module is enough to register them. Ref Uninett#4094 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

The v1 views handle query parameters, responses and pagination manually, which drf-spectacular cannot infer. Add extend_schema annotations and serializer hints so query parameters, response bodies and status codes are described accurately in the generated schema. Ref Uninett#4094 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Expose the generated schema at /api/schema/ and add interactive browsers at /api/schema/swagger-ui/ and /api/schema/redoc/. Integration tests assert the endpoints render and the schema validates. Ref Uninett#4094 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Check in the generated schema as a machine-readable artifact so API consumers can retrieve it without running NAV, and so schema changes are visible in review and in git blame. A later commit adds a CI check that keeps this snapshot in sync with the code. Ref Uninett#4094 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Add a tox environment that regenerates the schema and fails on any drift from the committed doc/api/openapi.yml, plus a GitHub Actions workflow that runs it. The spec version is normalized to a fixed placeholder so the snapshot is reproducible across tagged and untagged builds. Ref Uninett#4094 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Describe the schema endpoint and the Swagger UI and ReDoc browsers in the API how-to, and add the changelog fragment for the feature. Closes Uninett#4094 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

The schema endpoints (/api/schema/, /swagger-ui/, /redoc/) are served by drf-spectacular's views, which build the OpenAPI schema on the fly from the running code on every request. The committed snapshot at doc/api/openapi.yml never took part in serving; it existed only as an offline copy and a target for a CI drift check. We don't need an offline spec or schema diffs in review, so the snapshot, its generator (tools/openapi_schema.py), the CI workflow and the openapi-schema tox environment are all pure maintenance overhead: every API change would otherwise require regenerating and re-committing the file. Remove them and rely on dynamic generation, which is always in sync with the code by construction. Trim the docs accordingly. Ref Uninett#4094 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

sonarqubecloud · 2026-07-10T06:53:49Z

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

adobloug force-pushed the drf-spectacular branch from 79ee0fb to 457b505 Compare June 19, 2026 08:40

adobloug changed the title ~~Add OpenAPI 3 specification with Swagger UI and ReDoc~~ Add OpenAPI 3 spec with Swagger UI and ReDoc Jun 19, 2026

johannaengland requested a review from a team June 23, 2026 09:10

johannaengland assigned adobloug Jun 23, 2026

johannaengland requested a review from lunkwill42 June 23, 2026 09:12

hmpf reviewed Jun 24, 2026

View reviewed changes

hmpf added api documentation Related to documentation of NAV dependencies Pull requests that update a dependency file labels Jun 24, 2026

hmpf requested a review from a team June 24, 2026 11:27

adobloug force-pushed the drf-spectacular branch from 457b505 to 212bc9c Compare July 9, 2026 05:55

lunkwill42 reviewed Jul 9, 2026

View reviewed changes

lunkwill42 mentioned this pull request Jul 9, 2026

Re-introduce OpenAPI schema documentation for NAV API #3380

Closed

lunkwill42 requested changes Jul 9, 2026

View reviewed changes

adobloug force-pushed the drf-spectacular branch from 212bc9c to 3ab7031 Compare July 9, 2026 10:55

adobloug and others added 9 commits July 10, 2026 08:50

Add drf-spectacular dependency

7925c61

drf-spectacular generates an OpenAPI 3 schema from Django REST Framework views. Add it as a runtime dependency; later commits wire it up to produce and serve NAV's API schema. Ref Uninett#4094 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Document the API schema and add changelog

afe3892

Describe the schema endpoint and the Swagger UI and ReDoc browsers in the API how-to, and add the changelog fragment for the feature. Closes Uninett#4094 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

adobloug force-pushed the drf-spectacular branch from 3ab7031 to 3ca4b0f Compare July 10, 2026 06:53

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add OpenAPI 3 spec with Swagger UI and ReDoc#4095

Add OpenAPI 3 spec with Swagger UI and ReDoc#4095
adobloug wants to merge 9 commits into
Uninett:masterfrom
adobloug:drf-spectacular

adobloug commented Jun 18, 2026 •

edited

Loading

Uh oh!

hmpf left a comment

Uh oh!

adobloug commented Jun 29, 2026 •

edited

Loading

Uh oh!

lunkwill42 left a comment

Uh oh!

lunkwill42 left a comment

Uh oh!

codecov Bot commented Jul 9, 2026

Uh oh!

adobloug commented Jul 9, 2026

Uh oh!

sonarqubecloud Bot commented Jul 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Conversation

adobloug commented Jun 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Details

Why both Swagger UI and ReDoc?

Testing

Checklist

Uh oh!

hmpf left a comment

Choose a reason for hiding this comment

Uh oh!

adobloug commented Jun 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

lunkwill42 left a comment

Choose a reason for hiding this comment

Uh oh!

lunkwill42 left a comment

Choose a reason for hiding this comment

Uh oh!

codecov Bot commented Jul 9, 2026

Codecov Report

Uh oh!

adobloug commented Jul 9, 2026

Uh oh!

sonarqubecloud Bot commented Jul 10, 2026

Quality Gate passed

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

adobloug commented Jun 18, 2026 •

edited

Loading

adobloug commented Jun 29, 2026 •

edited

Loading