All jobs

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 RushOpens 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 with this body:

{
  "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.

The use case this job follows, with its automation and trigger: Hand off a long task.

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

The same job on other stacks

Keep reading