# Add OpenAPI Docs to a Django REST Framework API

Yes. An agent adds drf-spectacular, annotates every APIView with its nested serializers, serves the schema and Swagger UI, validates the document, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-openapi-docs/django-rest-framework/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads how the API is written before it documents it, because the style decides how much the schema generator can infer. In a project shaped like HackSoftware/Django-Styleguide-Example, `requirements/base.txt` pins `Django==5.2.7`, `djangorestframework==3.16.1`, `drf-jwt`, `django-filter` and `django-cors-headers`, and `requirements/local.txt` adds `pytest`, `pytest-django`, `factory-boy`, `mypy` with `django-stubs` and `djangorestframework-stubs`, and `ruff`. `config/urls.py` mounts `styleguide_example.api.urls` at `api/`, which includes `auth/`, `users/`, `errors/`, `files/` and `google-oauth2/`. `REST_FRAMEWORK` in `config/django/base.py` sets a custom exception handler and the django-filter backend, and no schema class.

The views are plain `APIView` classes with nested serializers, the pattern the styleguide is known for. `users/apis.py` has `UserDetailApi` with an inner `OutputSerializer`, `UserListApi` with `Pagination`, `FilterSerializer` and `OutputSerializer`, `UserCreateApi` with `InputSerializer`, and `UserUpdateApi`; the method bodies build the serializer by hand, so no generator can see the request or response shape from the class alone. `api/utils.py` has `inline_serializer`, which creates serializer classes at runtime all named `inline_serializer`, and its comment already points at the drf-spectacular issue that causes: identical component names collide in the schema.

The agent adds `drf-spectacular` to `requirements/base.txt`, `drf_spectacular` to `THIRD_PARTY_APPS`, `DEFAULT_SCHEMA_CLASS` pointing at `drf_spectacular.openapi.AutoSchema` in `REST_FRAMEWORK`, and a `SPECTACULAR_SETTINGS` block with the title, version and `COMPONENT_SPLIT_REQUEST` on so input and output serializers become separate components. `api/urls.py` gets `schema/` served by `SpectacularAPIView` and `docs/` by `SpectacularSwaggerView`. Then it goes view by view: an `@extend_schema` on each method naming the nested `InputSerializer` as `request`, the `OutputSerializer` as the response, the `FilterSerializer` as `parameters` on list views, and the status codes the service layer can raise. `inline_serializer` gains a `name` argument so each call registers a distinct component, and every caller passes one.

The proof is the schema itself. `python manage.py spectacular --file schema.yml --validate --fail-on-warn` has to exit 0, which it does not until every nested serializer is named and every view annotated. A new test under `styleguide_example/api/tests` requests `/api/schema/` with the test client, asserts 200, and checks that the users paths and their components are present. The agent runs `pytest`, `ruff check .` and `mypy --config mypy.ini styleguide_example/`, the three commands `.github/workflows/django.yml` runs, and pushes only when all of them pass.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add OpenAPI documentation to this Django REST Framework API with drf-spectacular. Read requirements/base.txt, requirements/local.txt, config/django/base.py, config/urls.py, styleguide_example/api/urls.py, styleguide_example/api/utils.py, styleguide_example/api/mixins.py, styleguide_example/api/pagination.py, every apis.py and urls.py under styleguide_example, pytest.ini, mypy.ini and .github/workflows/django.yml first. Add drf-spectacular to the base requirements and to THIRD_PARTY_APPS, set DEFAULT_SCHEMA_CLASS and SPECTACULAR_SETTINGS with COMPONENT_SPLIT_REQUEST, and serve the schema at api/schema/ and Swagger UI at api/docs/. Annotate every APIView method with extend_schema using its nested InputSerializer, OutputSerializer and FilterSerializer and the statuses it returns, and give inline_serializer a required name so components do not collide. Run python manage.py spectacular --validate --fail-on-warn until it is clean, add a test that fetches /api/schema/ and checks the users paths, run pytest, ruff check . and mypy, and open a pull request that lists every documented endpoint.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

What comes back is a pull request on its own branch. `requirements/base.txt` gains `drf-spectacular`; `config/django/base.py` gains the app, the schema class and `SPECTACULAR_SETTINGS`; `styleguide_example/api/urls.py` gains the `schema/` and `docs/` routes; `api/utils.py` gains the `name` parameter on `inline_serializer`; every `apis.py` gains `@extend_schema` decorators and nothing else, so the service and selector calls are untouched; and a new test file sits under `styleguide_example/api/tests`. The description lists every endpoint with its method, request and response component names.

The checks are the proof. The repository's `Django application` workflow runs on the pull request in both of its jobs, the Docker Compose one and the native one against a Postgres service, each running `ruff check`, `mypy` and `pytest`, which now includes the schema test. The trajectory at `GET /o/{org}/sessions/{id}/messages` keeps the `spectacular --validate --fail-on-warn` output, so a reviewer sees that the generator raised no warning on any view rather than reading that it did.

Before merging, a reviewer opens `/api/docs/` on a local checkout, reads the components for the endpoints their clients call, and decides whether the schema route should sit behind `ApiAuthMixin` like the rest of the API or stay open for client generation. Nothing deploys until the pull request merges.

## Run it on every new API service

A developer starts this from the terminal when a service needs a schema: one `POST /o/{org}/sessions` with the repository in `resources` and this prompt, then walks away. The run clones the project into its own sandbox, installs `requirements/local.txt`, runs the generator and the three CI commands, and opens the pull request; the sandbox parks when the turn ends, and a follow-up through `POST /o/{org}/sessions/{id}/messages` wakes it, for a different title or an extra tag per app.

With a `webhook_url` on the API key, `run.completed` arrives with `data.session_url` to read for the pull request link, and a `request_id` per repository keeps a retried request from starting a second run. Several services can be documented at once, each in its own sandbox, up to the key's `max_concurrent`.

## Why run it on Rush?

Annotating a styleguide-shaped API is a long pass over every view, and the only honest check is the generator's own `--fail-on-warn` run, which stops at the first unnamed serializer and has to be repeated after every fix. On a laptop that loop runs beside a database and a Celery worker the project expects. In a Rush sandbox the agent installs the project, runs `spectacular --validate --fail-on-warn`, reads the warning, names the serializer or adds the decorator, and runs it again until the document is clean, with `pytest`, `ruff` and `mypy` at the end.

The pull request carries its proof: the repository's own workflow runs the same three commands on it, and the transcript keeps the generator output beside the commands. A second service, or the same one after a new app lands, is a second sandbox and a second pull request at the same time.

## Frequently asked questions

### Why does every view need a decorator?

Because the views are `APIView` classes that build their nested serializers inside the method body, which is the styleguide's deliberate pattern; a schema generator sees the class and not the body, so without `@extend_schema` it reports the endpoint with no request or response shape. The decorator names the nested `InputSerializer`, `OutputSerializer` and `FilterSerializer` that are already there, and the methods themselves do not change.

### What is the problem with inline_serializer?

Every class it creates is named `inline_serializer`, so two views using it produce two components with the same name and drf-spectacular warns about the collision, which the comment in `api/utils.py` already flags. The agent adds a required `name` argument and passes a distinct one at each call site, so each becomes its own component.

### Will the schema be behind authentication?

Not by default. `REST_FRAMEWORK` sets no default authentication, and the agent mounts `schema/` and `docs/` as open routes so client generators can fetch the document, which is the usual choice. If the API is private, the prompt can ask for `ApiAuthMixin` on both views, and the test then signs in before fetching.

### Does it generate client code too?

No. The run produces the schema and the Swagger UI page and stops there. A client for a TypeScript or Python consumer is a separate job that reads `/api/schema/`, and the schema test in this pull request is what keeps that document valid as the API changes.

## More Django REST Framework jobs

- [Add OpenTelemetry Tracing to a Django REST Framework API](https://getrush.ai/run/add-opentelemetry/django-rest-framework/)
- [Add a Password Change Endpoint to a Django REST Framework API from a Linear Issue](https://getrush.ai/run/add-password-change/django-rest-framework/)
- [Add a Password Reset API to a Django REST Framework Project](https://getrush.ai/run/add-password-reset/django-rest-framework/)

## The same job on other stacks

- [Serve OpenAPI Docs from a Fastify API from a Linear Issue](https://getrush.ai/run/add-openapi-docs/fastify/)
- [Add OpenAPI Docs to a Fiber App](https://getrush.ai/run/add-openapi-docs/fiber/)
- [Add OpenAPI Docs to a Flask API from a Linear Issue](https://getrush.ai/run/add-openapi-docs/flask/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
