<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Dacian Popuțe on Medium]]></title>
        <description><![CDATA[Stories by Dacian Popuțe on Medium]]></description>
        <link>https://medium.com/@dacianpopute?source=rss-48af112b451a------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*hSHigThoRkL3jfBA4-X5Gg.jpeg</url>
            <title>Stories by Dacian Popuțe on Medium</title>
            <link>https://medium.com/@dacianpopute?source=rss-48af112b451a------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Fri, 20 Nov 2026 16:45:31 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@dacianpopute/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[The drf-spectacular oneOf Schema You're Fighting? Here’s the Fix.]]></title>
            <link>https://dacianpopute.medium.com/the-drf-spectacular-oneof-schema-youre-fighting-heres-the-fix-322d2b4af9d7?source=rss-48af112b451a------2</link>
            <guid isPermaLink="false">https://medium.com/p/322d2b4af9d7</guid>
            <category><![CDATA[documentation]]></category>
            <category><![CDATA[open-api]]></category>
            <category><![CDATA[django-rest-framework]]></category>
            <category><![CDATA[rest-api]]></category>
            <category><![CDATA[software-engineering]]></category>
            <dc:creator><![CDATA[Dacian Popuțe]]></dc:creator>
            <pubDate>Sat, 04 Oct 2025 13:05:38 GMT</pubDate>
            <atom:updated>2025-10-04T13:06:25.330Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*RSJHi_tO1LmsdZldKfgGeA.avif" /></figure><h4>When PolymorphicProxySerializer doesn&#39;t fit a SerializerMethodField, the solution is a raw OpenAPI schema dictionary.</h4><p>Good API documentation is key to a great developer experience. As our APIs grow, we often hit complex patterns that require us to dig deeper into our tools. This is a look at one of those scenarios and a powerful technique to solve it.</p><p>The setup is a common one if you’re using <a href="https://www.django-rest-framework.org/"><strong>Django REST Framework</strong></a>: a polymorphic field whose structure changes based on another field’s value. For us, it was a config object in a payment methods API. If the type is credit_card, config has card details. If type is bank_transfer, it has bank details.</p><p>In the <strong>OpenAPI 3.0 specification</strong>, this is a textbook case for a oneOf schema. And drf-spectacular is a fantastic tool for generating these schemas automatically. However, when the polymorphic data comes from a SerializerMethodField, the standard approach doesn&#39;t quite fit.</p><p>Here’s a breakdown of the challenge and a clear, effective solution.</p><h3>The Common Approach: PolymorphicProxySerializer</h3><p>drf-spectacular provides a dedicated tool for polymorphism: PolymorphicProxySerializer. It’s designed to handle cases where an entire API response can be one of several different objects, and for that, it works perfectly.</p><p>But our challenge is different. We have a <em>single field</em> inside a serializer that is polymorphic, not the entire response. Applying the proxy serializer in this context leads to unexpected results.</p><p>Python</p><pre># A common first attempt that doesn&#39;t produce the desired schema<br>@extend_schema_field(PolymorphicProxySerializer(...))<br>def get_config(self, obj):<br>    # ... your logic here</pre><p>This code doesn’t produce an error, but it doesn’t produce a oneOf schema either. Because the tool is being used outside of its intended response-level context, drf-spectacular defaults to rendering the config field as a generic type: object.</p><p>This leaves API consumers without the structural information they need.</p><figure><img alt="The beforee screenshot, showing Redoc rendering the `config` field as a generic, un-detailed object" src="https://cdn-images-1.medium.com/max/812/1*-eEhmTTeHG-1hwp12Erc6g.png" /><figcaption>Before the fix, the <strong>config</strong> field renders as a generic object, hiding the different possible structures.</figcaption></figure><p><em>Before the fix, the </em><em>config field renders as a generic object, hiding the different possible structures.</em></p><h3>The Fix: Drop Down to a Raw OpenAPI Schema</h3><p>When an abstraction doesn’t fit a specific use case, the best solution is often to work at a lower level. The @extend_schema_field decorator provides an escape hatch for exactly this: it accepts a raw Python dict that represents a valid <strong>OpenAPI</strong> schema.</p><p>This lets you bypass the auto-detection and define the schema for your SerializerMethodField directly. You provide the precise structure, and drf-spectacular renders it.</p><p>Python</p><pre>from drf_spectacular.utils import extend_schema_field<br>from rest_framework import serializers<br><br><br>class PaymentMethodSerializer(serializers.ModelSerializer):<br>    config = serializers.SerializerMethodField()<br>    @extend_schema_field({<br>        &quot;oneOf&quot;: [<br>            {<br>                &quot;title&quot;: &quot;Credit Card Configuration&quot;,<br>                &quot;type&quot;: &quot;object&quot;,<br>                &quot;properties&quot;: {<br>                    &quot;card_network&quot;: {&quot;type&quot;: &quot;string&quot;, &quot;enum&quot;: [&quot;visa&quot;, &quot;mastercard&quot;]},<br>                    &quot;supports_3ds&quot;: {&quot;type&quot;: &quot;boolean&quot;}<br>                },<br>                &quot;required&quot;: [&quot;card_network&quot;, &quot;supports_3ds&quot;],<br>            },<br>            {<br>                &quot;title&quot;: &quot;Bank Transfer Configuration&quot;,<br>                &quot;type&quot;: &quot;object&quot;,<br>                &quot;properties&quot;: {<br>                    &quot;bank_code&quot;: {&quot;type&quot;: &quot;string&quot;},<br>                    &quot;account_type&quot;: {&quot;type&quot;: &quot;string&quot;, &quot;enum&quot;: [&quot;checking&quot;, &quot;savings&quot;]}<br>                },<br>                &quot;required&quot;: [&quot;bank_code&quot;],<br>            },<br>            {<br>                &quot;title&quot;: &quot;Digital Wallet Configuration&quot;,<br>                &quot;type&quot;: &quot;object&quot;,<br>                &quot;properties&quot;: {}, # Explicitly an empty object<br>                &quot;description&quot;: &quot;No additional configuration is needed.&quot;<br>            }<br>        ],<br>        &quot;description&quot;: &quot;Structure depends on the &#39;type&#39; field.&quot;<br>    })<br>    def get_config(self, obj):<br>        # ... logic to return the correct config dict</pre><p>This approach is both powerful and reliable because it’s explicit.</p><ul><li>The <strong>oneOf</strong> array clearly lists every possible schema structure.</li><li>The <strong>title</strong> key provides a human-readable name for each schema in the API docs UI, which is crucial for usability.</li><li>You have full control over properties, types, patterns, and <strong>required</strong> fields.</li></ul><p>The result is clean, interactive, and accurate documentation that correctly communicates how your API works.</p><figure><img alt="The after screenshot, showing Redoc rendering the `config` field with an interactive ‘oneOf’ dropdown menu" src="https://cdn-images-1.medium.com/max/773/1*P5Re7AbB4bEa0tsYH9OuBw.png" /><figcaption>After the fix, the documentation is interactive, with a <strong>oneOf</strong> dropdown that lets developers explore each configuration schema.</figcaption></figure><p><em>After the fix, the documentation is interactive, allowing developers to switch between the different configuration schemas.</em></p><h3>A Simple Rule: When to Use This Technique</h3><p>This raw schema approach is a scalpel, not a sledgehammer. It’s for specific, advanced use cases.</p><ul><li><strong>Use raw schemas when:</strong> You have a SerializerMethodField that returns a dynamic or polymorphic structure and the standard tools don&#39;t apply.</li><li><strong>Stick with auto-generation when:</strong> You are using standard ModelSerializers or simple DRF fields. The automation in drf-spectacular is powerful and should be leveraged for the 90% of cases it handles perfectly.</li></ul><p>The takeaway is that powerful tools like drf-spectacular often include flexible, lower-level APIs for handling edge cases. By understanding when to step outside the abstractions, you can produce clear and accurate documentation for even the most complex parts of your system.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=322d2b4af9d7" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>