{"id":320,"date":"2026-11-19T12:00:00","date_gmt":"2026-11-19T12:00:00","guid":{"rendered":"https:\/\/rezachegini.com\/?p=320"},"modified":"2026-11-19T19:38:05","modified_gmt":"2026-11-19T19:38:05","slug":"building-a-job-board-api-part-22-api-docs-that-tell-the-truth","status":"publish","type":"post","link":"https:\/\/rezachegini.com\/?p=320","title":{"rendered":"Building a Job Board API, Part 22: API Docs That Tell the Truth"},"content":{"rendered":"<p>I&#8217;m sharing one of my projects here from the beginning, step by step. It&#8217;s a Job Board API built with Django, Django REST Framework, PostgreSQL and Docker Compose, with S3 and SQS (through LocalStack), Redis, and a background worker.<\/p>\n<p>I&#8217;m a junior engineer looking for my first role in DevOps, SRE or Cloud. That&#8217;s why I build projects like this and write about them in public. It shows how I think, and writing it down helps me really understand it.<\/p>\n<p>Parts 18 to 21 gave the API 194 tests and 100% coverage. This part gives it documentation: an OpenAPI schema, and Swagger UI, an interactive page in the browser that lists every endpoint and lets you try it without writing a line of code.<\/p>\n<p>The docs are generated from the code by a library called drf-spectacular. That sounds like they can&#8217;t be wrong: if the code is right, the docs are right. It isn&#8217;t true. A generated schema can be valid, pass every check, and still say the wrong thing, because the generator can only describe what it can see. It doesn&#8217;t know what the view actually returns.<\/p>\n<p>So this article is really about one lesson: &#8220;no warning&#8221; doesn&#8217;t mean &#8220;correct&#8221;. You have to read what the docs say, not just whether they validate. Along the way, I&#8217;ll show how I added OpenAPI docs with drf-spectacular, found four operations the docs described wrong, fixed six problems in total, and added nine tests so the docs can&#8217;t quietly go wrong again.<\/p>\n<h3 class=\"wp-block-heading\">The setup<\/h3>\n<pre class=\"wp-block-code\"><code>uv add \"drf-spectacular&gt;=0.30\"<\/code><\/pre>\n<ul class=\"wp-block-list\">\n<li>A runtime dependency, not a dev one. The running app serves the docs, so I rebuilt all three images: docker compose build api worker test.<\/li>\n<li>Why &gt;=0.30? Version 0.29 added DRF 3.16 support, and 0.30.0 fixed the Django 5.2 dependency definition. The API runs Django 5.2 and DRF 3.16, so 0.30 was the first version that fit.<\/li>\n<li>It also brings PyYAML (for the YAML output) and jsonschema (for validating the schema).<\/li>\n<\/ul>\n<p>In config\/settings.py, three changes. First, &#8220;drf_spectacular&#8221; goes into INSTALLED_APPS. That registers the spectacular management command and the Swagger UI template. Second:<\/p>\n<pre class=\"wp-block-code\"><code>REST_FRAMEWORK = {\n    # ...\n    \"DEFAULT_SCHEMA_CLASS\": \"drf_spectacular.openapi.AutoSchema\",\n}<\/code><\/pre>\n<p>DRF asks each view&#8217;s schema object to describe that view. This line makes drf-spectacular&#8217;s AutoSchema the schema object for every DRF view, so it inspects the serializers, permissions, authentication, pagination and filters. Without it, DRF&#8217;s built-in generator would still be used, and the docs would be the old ones.<\/p>\n<p>Third:<\/p>\n<pre class=\"wp-block-code\"><code>SPECTACULAR_SETTINGS = {\n    \"TITLE\": \"Job Board API\",\n    \"DESCRIPTION\": \"Companies post jobs; candidates apply with a resume. JWT auth: get a token from \/api\/auth\/token\/ and click Authorize.\",\n    \"VERSION\": \"1.0.0\",\n    \"SERVE_INCLUDE_SCHEMA\": False,\n    \"COMPONENT_SPLIT_REQUEST\": True,\n}<\/code><\/pre>\n<ul class=\"wp-block-list\">\n<li>TITLE, DESCRIPTION and VERSION are the header of the Swagger page. The description tells a first-time reader what the API does and how to log in: get a token from \/api\/auth\/token\/ and click Authorize in Swagger UI.<\/li>\n<li>VERSION is the API&#8217;s version, not the app&#8217;s. It changes when the API contract changes.<\/li>\n<li>SERVE_INCLUDE_SCHEMA: False: the schema endpoint doesn&#8217;t list itself as an API operation.<\/li>\n<li>COMPONENT_SPLIT_REQUEST: True is the important one. It creates separate components for what clients send and what they receive: ApplicationRequest and Application, JobRequest and Job. My API needs that:\n<ul class=\"wp-block-list\">\n<li>resume is write-only: it&#8217;s in the request, as a file, and never in the response<\/li>\n<li>has_resume, match_score, id and the timestamps are read-only: they&#8217;re only in the response.<\/li>\n<\/ul>\n<p>With one shared component, the docs would show resume in responses and match_score as something you can send.<\/li>\n<\/ul>\n<h3 class=\"wp-block-heading\">The URLs<\/h3>\n<pre class=\"wp-block-code\"><code>from drf_spectacular.views import SpectacularAPIView, SpectacularSwaggerView\n\nurlpatterns = [\n    path(\"\", include(\"django_prometheus.urls\")),\n    path(\"api\/schema\/\", SpectacularAPIView.as_view(), name=\"schema\"),\n    path(\"api\/schema\/swagger-ui\/\", SpectacularSwaggerView.as_view(url_name=\"schema\"), name=\"swagger-ui\"),\n    path(\"api\/\", include(\"jobs.urls\")),\n]<\/code><\/pre>\n<ul class=\"wp-block-list\">\n<li>\/api\/schema\/ returns the schema as YAML, with the official OpenAPI content type application\/vnd.oai.openapi.<\/li>\n<li>\/api\/schema\/swagger-ui\/ returns an HTML page that loads Swagger UI. url_name=&#8221;schema&#8221; tells it where to fetch the schema from.<\/li>\n<li>The specific paths come before api\/. Django tries patterns from top to bottom. There&#8217;s no clash today: \/api\/schema\/ and \/api\/ both start with api\/, but Django matches the more specific one first, and the order makes the intent obvious.<\/li>\n<li>The docs are public. drf-spectacular serves them to anyone by default. That&#8217;s fine for a portfolio API: the docs show shapes, not data. But anything under \/api\/ is still JWT-protected.<\/li>\n<li>Swagger UI&#8217;s JavaScript and CSS come from a public CDN, loaded by the browser. gunicorn doesn&#8217;t serve any static files, and there&#8217;s nothing to collect.<\/li>\n<\/ul>\n<p>\/healthz, \/readyz and \/metrics are not in the schema, and that&#8217;s correct. They&#8217;re plain Django views, not DRF views, so drf-spectacular doesn&#8217;t see them.<\/p>\n<p>The schema found JWT on its own. Its securitySchemes section has jwtAuth: type http, scheme bearer, bearerFormat JWT. drf-spectacular reads the SimpleJWT authentication classes and describes them. It also marks every operation as needing JWT, because the views have IsAuthenticated or a permission class that requires a user.<\/p>\n<h3 class=\"wp-block-heading\">The first checks: everything looked fine<\/h3>\n<ol class=\"wp-block-list\">\n<li>curl -i \/api\/schema\/ returned 200, with the OpenAPI content type, openapi: 3.0.3, and my title, version and description.<\/li>\n<li>11 paths, all under \/api\/: 4 for auth, 3 for jobs and 4 for applications. Every DRF endpoint was documented.<\/li>\n<li>The security scheme: jwtAuth, type: http, scheme: bearer.<\/li>\n<li>Swagger UI returned 200.<\/li>\n<li>Validation: python manage.py spectacular &#8211;validate said Errors: 0 and Warnings: 6 (2 unique). Both warnings were the same kind, on get_has_resume and get_match_score: &#8220;unable to resolve type hint &#8230; Defaulting to string&#8221;.<\/li>\n<li>The test suite: still 194 passed, 100%. Installing the app broke nothing.<\/li>\n<\/ol>\n<p>A valid schema, zero errors, and two small warnings. Most people would stop here.<\/p>\n<h3 class=\"wp-block-heading\">Reading what the schema actually says<\/h3>\n<p>Instead of stopping, I wrote a small script that prints one line per operation: the component it accepts as a request, and the component it returns for each status code.<\/p>\n<pre class=\"wp-block-code\"><code>import yaml\n\nschema = yaml.safe_load(open(\"\/tmp\/schema.yml\"))\n\ndef name(s):\n    return s.get(\"$ref\", \"\").split(\"\/\")[-1] or s.get(\"type\", \"?\")\n\nfor path, ops in schema[\"paths\"].items():\n    for method, op in ops.items():\n        request = sorted({name(v[\"schema\"]) for v in op.get(\"requestBody\", {}).get(\"content\", {}).values()})\n        responses = {code: sorted({name(v[\"schema\"]) for v in r.get(\"content\", {}).values()}) or \"-\" for code, r in op[\"responses\"].items()}\n        print(f\"{method.upper():6} {path:40} request={request or '-'} responses={responses}\")<\/code><\/pre>\n<ul class=\"wp-block-list\">\n<li>$ref is OpenAPI&#8217;s pointer to a reusable component, like #\/components\/schemas\/Application. split(&#8220;\/&#8221;)[-1] keeps just the name.<\/li>\n<li>The rest walks the schema&#8217;s structure: paths, then operations (GET, POST&#8230;), then the request body and the responses. If a part is missing, .get() returns {} instead of raising, so the script keeps going.<\/li>\n<\/ul>\n<p>Reading that output against the code, I found 4 operations that were wrong, and none of them had a warning:<\/p>\n<figure class=\"wp-block-image size-full\"><img loading=\"lazy\" decoding=\"async\" src=\"http:\/\/rezachegini.com\/wp-content\/uploads\/2026\/11\/job-board-api-part-22-diagram.png\" alt=\"Four operations the schema got wrong, without a single warning\" class=\"wp-image-319\" width=\"1442\" height=\"653\" srcset=\"https:\/\/rezachegini.com\/wp-content\/uploads\/2026\/11\/job-board-api-part-22-diagram.png 1442w, https:\/\/rezachegini.com\/wp-content\/uploads\/2026\/11\/job-board-api-part-22-diagram-300x136.png 300w, https:\/\/rezachegini.com\/wp-content\/uploads\/2026\/11\/job-board-api-part-22-diagram-1024x464.png 1024w, https:\/\/rezachegini.com\/wp-content\/uploads\/2026\/11\/job-board-api-part-22-diagram-768x348.png 768w\" sizes=\"auto, (max-width: 1442px) 100vw, 1442px\" \/><\/figure>\n<p>These aren&#8217;t small mistakes. A developer reading these docs would send the wrong body to change a status, expect a whole application from the resume link, and expect one job from the applicants endpoint. A client generated from this schema would simply be broken.<\/p>\n<h3 class=\"wp-block-heading\">Why there was no warning<\/h3>\n<p>For a custom @action, and for a view with a custom to_representation, the generator does have a serializer to use: the view&#8217;s serializer_class. It&#8217;s just the wrong one. For example, JobViewSet.serializer_class is JobSerializer, so the applications action was documented as returning a Job. The resume endpoint&#8217;s ApplicationViewSet.serializer_class is ApplicationSerializer, so it was documented as returning a whole application. The generator filled in the answer with the nearest serializer it could see, and never said it was guessing.<\/p>\n<p>drf-spectacular only warns when it has nothing to go on. When it has the wrong thing, it says nothing. That&#8217;s why reading the content matters more than the validator&#8217;s result.<\/p>\n<h3 class=\"wp-block-heading\">Fixing all six problems<\/h3>\n<h3 class=\"wp-block-heading\">The 2 warnings: type hints<\/h3>\n<pre class=\"wp-block-code\"><code>def get_has_resume(self, obj) -&gt; bool:\n    return bool(obj.resume)\n\ndef get_match_score(self, obj) -&gt; int | None:\n    return matching.match_score(obj.job.required_skills, obj.candidate.skills)<\/code><\/pre>\n<ul class=\"wp-block-list\">\n<li>A SerializerMethodField gets its value from a method, so drf-spectacular can&#8217;t know the type by looking at the field. Without a hint, it warns and falls back to type: string.<\/li>\n<li>Without the hints, the docs said has_resume and match_score were strings. A client generated from the schema would have treated 50 as text.<\/li>\n<li>int | None (Python 3.10+ for &#8220;an int or None&#8221;) becomes type: integer, nullable: true. That&#8217;s exactly match_score: null when the job lists no skills, as tested in Part 18.<\/li>\n<li>The hints change nothing at runtime. Python doesn&#8217;t enforce them. The type hint is the documentation here.<\/li>\n<\/ul>\n<h3 class=\"wp-block-heading\">Two small serializers that build the real responses<\/h3>\n<pre class=\"wp-block-code\"><code>class RegisteredUserSerializer(serializers.Serializer):\n    id = serializers.IntegerField(read_only=True)\n    username = serializers.CharField(read_only=True)\n    email = serializers.EmailField(read_only=True)\n    role = serializers.ChoiceField(choices=User.Role.choices, read_only=True)\n\nclass ResumeLinkSerializer(serializers.Serializer):\n    url = serializers.URLField(read_only=True)\n    expires_in = serializers.IntegerField(read_only=True, help_text=\"Seconds until the link stops working.\")<\/code><\/pre>\n<ul class=\"wp-block-list\">\n<li>RegisteredUserSerializer is the exact shape the signup endpoints return. ChoiceField(choices=User.Role.choices) makes role an enum of &#8220;company&#8221; and &#8220;candidate&#8221;, and the values are already lowercase, as tested in Part 19.<\/li>\n<li>ResumeLinkSerializer is the resume endpoint&#8217;s response. help_text becomes the field&#8217;s description in the docs, so the client knows what the number means.<\/li>\n<\/ul>\n<p>The important part is how I used them. I could have written these serializers only for the docs, and kept building responses by hand. Instead, the views now build their responses with these serializers, so the docs and the real responses are the same object:<\/p>\n<pre class=\"wp-block-code\"><code>def to_representation(self, user):\n    return RegisteredUserSerializer(user).data<\/code><\/pre>\n<p>Before, this was a hand-built dict with id, username, email and role. The output is the same keys and values, just built by the serializer now.<\/p>\n<p>Proven unchanged: the registration tests from Part 19 (role, email lower-casing, no password in the response) still pass.<\/p>\n<h3 class=\"wp-block-heading\">@extend_schema: telling the generator the truth<\/h3>\n<p>@extend_schema is a decorator that overrides what drf-spectacular infers, for one operation or a whole view.<\/p>\n<p>The signup views, on the class, so it applies to their one POST:<\/p>\n<pre class=\"wp-block-code\"><code>@extend_schema(responses={201: RegisteredUserSerializer})\nclass CompanyRegisterView(generics.CreateAPIView):<\/code><\/pre>\n<p>The status code is explicit, because CreateAPIView answers 201 Created. The request side was already correct, with password write-only.<\/p>\n<p>The applicants list:<\/p>\n<pre class=\"wp-block-code\"><code>@extend_schema(responses=ApplicationSerializer(many=True))\n@action(detail=True, methods=[\"get\"])<\/code><\/pre>\n<p>ApplicationSerializer(many=True) means a list of applications. For a GET list, drf-spectacular also adds pagination (PaginatedApplicationList), because pagination is on.<\/p>\n<p>@extend_schema must go above @action. Decorators apply from the bottom up. @action first registers the method as a route, then @extend_schema sees the registered action and can attach the schema to it. The other way around, @extend_schema would run before the method is an action, and the override would silently not apply.<\/p>\n<p>The status change:<\/p>\n<pre class=\"wp-block-code\"><code>@extend_schema(request=ApplicationStatusSerializer, responses=ApplicationSerializer)\n@action(detail=True, methods=[\"patch\"], url_path=\"status\")\ndef set_status(self, request, pk=None):<\/code><\/pre>\n<p>request= is what the view really validates with: just status. responses= is what it really returns: the updated application.<\/p>\n<p>The resume link:<\/p>\n<pre class=\"wp-block-code\"><code>@extend_schema(\n    responses={\n        200: ResumeLinkSerializer,\n        404: OpenApiResponse(description=\"This application has no resume.\"),\n    }\n)\n@action(detail=True, methods=[\"get\"])\ndef resume(self, request, pk=None):<\/code><\/pre>\n<ul class=\"wp-block-list\">\n<li>Two documented responses: 200 with the link, and 404 for applications without a resume. That 404 is the only error response I documented. A client needs to know when to expect it.<\/li>\n<li>OpenApiResponse describes a response with no body schema, just a description.<\/li>\n<li>The response is built with the serializer, like the signup: a dict goes into ResumeLinkSerializer(&#8230;) and .data comes out, so the real response matches the documented shape.<\/li>\n<\/ul>\n<p>Proven unchanged: in dev, the resume response still has a presigned url (with X-Amz-Expires=300 and the file&#8217;s key), and the tests that check it still pass.<\/p>\n<h3 class=\"wp-block-heading\">Tests for the docs<\/h3>\n<p>Fixing the schema once isn&#8217;t enough. A future change could break it again, silently, just like the first four did. So I added nine tests in test_docs.py. They test the content of the generated schema, not just that it validates.<\/p>\n<pre class=\"wp-block-code\"><code>@pytest.fixture(scope=\"module\")\ndef schema():\n    return SchemaGenerator().get_schema(request=None, public=True)<\/code><\/pre>\n<ul class=\"wp-block-list\">\n<li>SchemaGenerator().get_schema(&#8230;) builds the same dictionary that \/api\/schema\/ serves. public=True means it builds the public schema, the one anyone can read.<\/li>\n<li>scope=&#8221;module&#8221; generates it once for the whole file. Generation inspects every view, so doing it for every test would be slow.<\/li>\n<li>No database needed: generation only reads code.<\/li>\n<\/ul>\n<h3 class=\"wp-block-heading\">The warning gate<\/h3>\n<pre class=\"wp-block-code\"><code>def test_schema_is_valid_and_has_no_warnings(tmp_path):\n    out = tmp_path \/ \"schema.yml\"\n\n    call_command(\"spectacular\", \"--validate\", \"--fail-on-warn\", \"--file\", str(out))\n    assert out.read_text().startswith(\"openapi: 3.0.3\")<\/code><\/pre>\n<ul class=\"wp-block-list\">\n<li>&#8211;fail-on-warn makes the command fail on any warning, and &#8211;validate makes it fail on an invalid schema.<\/li>\n<li>call_command runs a management command from Python, exactly like manage.py spectacular &#8230;, but inside a test, so a failure fails the test.<\/li>\n<li>tmp_path is a pytest fixture that gives each test a fresh temporary folder, deleted afterwards.<\/li>\n<\/ul>\n<p>This is a second gate next to the 80% coverage gate from Part 21.<\/p>\n<h3 class=\"wp-block-heading\">But warnings weren&#8217;t the real problem<\/h3>\n<p>The warning gate alone would not have caught the 4 silent errors, because they never warned. So each of the 4 operations gets its own test, checking what the docs say it accepts and returns:<\/p>\n<pre class=\"wp-block-code\"><code>def test_resume_link_operation(schema):\n    responses = schema[\"paths\"][\"\/api\/applications\/{id}\/resume\/\"][\"get\"][\"responses\"]\n    assert ref(responses[\"200\"][\"content\"]) == \"ResumeLink\"\n    assert set(component(schema, \"ResumeLink\")[\"properties\"]) == {\"url\", \"expires_in\"}\n    assert \"404\" in responses<\/code><\/pre>\n<p>ref() turns a $ref pointer into the component name, and component() looks the component up. The component is named after the serializer: ResumeLinkSerializer becomes ResumeLink.<\/p>\n<pre class=\"wp-block-code\"><code>def test_status_operation_takes_only_a_status(schema):\n    operation = schema[\"paths\"][\"\/api\/applications\/{id}\/status\/\"][\"patch\"]\n    request_name = ref(operation[\"requestBody\"][\"content\"])\n    assert \"ApplicationStatus\" in request_name\n    assert set(component(schema, request_name)[\"properties\"]) == {\"status\"}\n    assert ref(operation[\"responses\"][\"200\"][\"content\"]) == \"Application\"<\/code><\/pre>\n<p>This one checks the meaning, not the exact name: the name contains ApplicationStatus, and the only field is status. The real name is PatchedApplicationStatus, from COMPONENT_SPLIT_REQUEST: a PATCH only sends some fields, so the request component is named Patched&#8230;<\/p>\n<p>The other tests:<\/p>\n<ul class=\"wp-block-list\">\n<li>The applicants list returns PaginatedApplicationList.<\/li>\n<li>Both signup endpoints return RegisteredUser, with exactly id, username, email and role.<\/li>\n<li>The application fields are typed: has_resume is a boolean, match_score is a nullable integer, resume is absent from the response, and in the request resume has format: binary. That last one is COMPONENT_SPLIT_REQUEST at work, and it&#8217;s how Swagger UI knows to show a file picker.<\/li>\n<li>The docs are public: \/api\/schema\/ and Swagger UI return 200 with no login. Someone who doesn&#8217;t have an account yet still needs to read the docs.<\/li>\n<li>JWT is documented exactly: {&#8220;type&#8221;: &#8220;http&#8221;, &#8220;scheme&#8221;: &#8220;bearer&#8221;, &#8220;bearerFormat&#8221;: &#8220;JWT&#8221;}. That&#8217;s what the Authorization header really needs: Bearer &lt;token&gt;.<\/li>\n<\/ul>\n<h3 class=\"wp-block-heading\">The results<\/h3>\n<ol class=\"wp-block-list\">\n<li>spectacular &#8211;validate &#8211;fail-on-warn exits with code 0: no warnings, valid schema.<\/li>\n<li>The operation table again: resume returns ResumeLink plus a 404; status takes PatchedApplicationStatus and returns Application; applicants returns PaginatedApplicationList; both signup endpoints return RegisteredUser.<\/li>\n<li>The full suite: 203 passed in 6.15 seconds, still 100% coverage (687 statements). That&#8217;s the 9 new schema tests on top of the 194 from Parts 18 to 21.<\/li>\n<li>The real resume response in dev is unchanged: a presigned url and &#8220;expires_in&#8221;: 300.<\/li>\n<\/ol>\n<pre class=\"wp-block-code\"><code>docker compose exec api python manage.py spectacular --validate --fail-on-warn --file \/tmp\/schema.yml   # Warnings: 0<\/code><\/pre>\n<h3 class=\"wp-block-heading\">One known inaccuracy, on purpose<\/h3>\n<p>The docs still say one small thing that isn&#8217;t quite true. For any PATCH request, drf-spectacular names the request component Patched&#8230; and marks every field as not required. My set_status action isn&#8217;t partial: status is required, and an empty body gets 400 (tested in Part 19).<\/p>\n<p>I could fix this with a custom AutoSchema subclass. But that&#8217;s a lot of machinery for one field that is already documented correctly in the request body: the schema says status is required, because the serializer says so. So I&#8217;m leaving the Patched&#8230; name in place, and writing it down here instead.<\/p>\n<h3 class=\"wp-block-heading\">Why I chose this way<\/h3>\n<ul class=\"wp-block-list\">\n<li>drf-spectacular. It&#8217;s maintained, it produces OpenAPI 3, and it understands SimpleJWT, django-filter and pagination. DRF&#8217;s built-in schema is older and less accurate, and drf-yasg only supports OpenAPI 2.<\/li>\n<li>Public docs. It&#8217;s a portfolio API, and the docs show shapes, not data.<\/li>\n<li>Swagger UI from a CDN. No static files to serve from gunicorn.<\/li>\n<li>COMPONENT_SPLIT_REQUEST. Write-only and read-only fields shown correctly.<\/li>\n<li>Responses built with the documented serializers, so the docs and the responses can&#8217;t drift apart.<\/li>\n<li>Type hints instead of @extend_schema_field. Shorter, and they also help editors and people reading the code.<\/li>\n<li>Tests on component names and fields, because &#8211;fail-on-warn alone misses silent errors.<\/li>\n<li>Error responses documented only where they mean something (the resume 404). Documenting 400, 401 and 403 everywhere would add noise.<\/li>\n<\/ul>\n<h3 class=\"wp-block-heading\">Try it yourself<\/h3>\n<p>Open \/api\/schema\/swagger-ui\/ in a browser. Run POST \/api\/auth\/token\/ with a username and password, click Authorize, paste the token, and try POST \/api\/jobs\/ with the body from the schema. Then change a status and see what the docs say the request should be.<\/p>\n<h3 class=\"wp-block-heading\">What I learned<\/h3>\n<ul class=\"wp-block-list\">\n<li>No warning doesn&#8217;t mean correct. When a custom action has no serializer of its own, drf-spectacular falls back to the view&#8217;s serializer_class, and that&#8217;s often the wrong shape.<\/li>\n<li>Read what the docs say, not just whether they validate. A 10-line script that prints one line per operation catches what the validator can&#8217;t.<\/li>\n<li>COMPONENT_SPLIT_REQUEST separates what clients send from what they receive.<\/li>\n<li>A type hint is documentation. -&gt; int | None becomes a nullable integer.<\/li>\n<li>One serializer for both the response and the docs keeps them from drifting apart.<\/li>\n<li>@extend_schema goes above @action, because decorators apply from the bottom up.<\/li>\n<li>Test the content of generated docs, not only their format.<\/li>\n<li>A warning gate (&#8211;fail-on-warn) sits well next to a coverage gate.<\/li>\n<li>Write down the inaccuracies you choose to keep.<\/li>\n<\/ul>\n<h3 class=\"wp-block-heading\">What comes next<\/h3>\n<p>This completes the second item of Phase 5: OpenAPI docs with drf-spectacular. The API now has 203 tests, 100% coverage, and documentation that&#8217;s tested too. I&#8217;ll keep writing up the rest of Phase 5 here.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>I&#8217;m sharing one of my projects here from the beginning, step by step. It&#8217;s a Job Board API built with Django, Django&hellip;<\/p>\n","protected":false},"author":2,"featured_media":318,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_rezaops_part":"22","_rezaops_linkedin_url":"https:\/\/www.linkedin.com\/pulse\/building-job-board-api-part-22-docs-tell-truth-reza-chegini-mtmjc\/","footnotes":""},"categories":[10,116],"tags":[214,8,111,191,218,118,216,25,112,217,213],"series":[117],"class_list":["post-320","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-devops","category-django","tag-coverage","tag-devops","tag-django","tag-drf","tag-drf-spectacular","tag-job-board","tag-openapi","tag-python","tag-rest-api","tag-swagger","tag-testing","series-job-board-api"],"jetpack_featured_media_url":"https:\/\/rezachegini.com\/wp-content\/uploads\/2026\/11\/job-board-api-part-22-cover.png","_links":{"self":[{"href":"https:\/\/rezachegini.com\/index.php?rest_route=\/wp\/v2\/posts\/320","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/rezachegini.com\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/rezachegini.com\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/rezachegini.com\/index.php?rest_route=\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/rezachegini.com\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=320"}],"version-history":[{"count":1,"href":"https:\/\/rezachegini.com\/index.php?rest_route=\/wp\/v2\/posts\/320\/revisions"}],"predecessor-version":[{"id":321,"href":"https:\/\/rezachegini.com\/index.php?rest_route=\/wp\/v2\/posts\/320\/revisions\/321"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/rezachegini.com\/index.php?rest_route=\/wp\/v2\/media\/318"}],"wp:attachment":[{"href":"https:\/\/rezachegini.com\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=320"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/rezachegini.com\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=320"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/rezachegini.com\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=320"},{"taxonomy":"series","embeddable":true,"href":"https:\/\/rezachegini.com\/index.php?rest_route=%2Fwp%2Fv2%2Fseries&post=320"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}