You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
<pstyle="text-align: center"><strong>Page not found</strong></p>
422
-
<pstyle="text-align: center">Try the <ahref="https://www.django-rest-framework.org/">homepage</a>, or <ahref="#searchModal" data-toggle="modal">search the documentation</a>.</p>
422
+
<pstyle="text-align: center">Try the <ahref="/">homepage</a>, or <ahref="#mkdocs_search_modal" data-toggle="modal">search the documentation</a>.</p>
<p>If you want to create a custom field, you'll need to subclass <code>Field</code> and then override either one or both of the <code>.to_representation()</code> and <code>.to_internal_value()</code> methods. These two methods are used to convert between the initial datatype, and a primitive, serializable datatype. Primitive datatypes will typically be any of a number, string, boolean, <code>date</code>/<code>time</code>/<code>datetime</code> or <code>None</code>. They may also be any list or dictionary like object that only contains other primitive objects. Other types might be supported, depending on the renderer that you are using.</p>
1042
1042
<p>The <code>.to_representation()</code> method is called to convert the initial datatype into a primitive, serializable datatype.</p>
1043
1043
<p>The <code>to_internal_value()</code> method is called to restore a primitive datatype into its internal python representation. This method should raise a <code>serializers.ValidationError</code> if the data is invalid.</p>
1044
-
<p>Note that the <code>WritableField</code> class that was present in version 2.x no longer exists. You should subclass <code>Field</code> and override <code>to_internal_value()</code> if the field supports data input.</p>
raise ValidationError('You have already signed up')
679
679
serializer.save(user=self.request.user)
680
680
</code></pre>
681
-
<p><strong>Note</strong>: These methods replace the old-style version 2.x <code>pre_save</code>, <code>post_save</code>, <code>pre_delete</code> and <code>post_delete</code> methods, which are no longer available.</p>
682
681
<p><strong>Other methods</strong>:</p>
683
682
<p>You won't typically need to override the following methods, although you might need to call into them if you're writing custom views using <code>GenericAPIView</code>.</p>
<li><code>pyyaml</code> is used to generate schema into YAML-based OpenAPI format.</li>
457
+
<li><code>uritemplate</code> is used internally to get parameters in path.</li>
458
+
</ul>
457
459
<h3id="generating-a-static-schema-with-the-generateschema-management-command"><aclass="toclink" href="#generating-a-static-schema-with-the-generateschema-management-command">Generating a static schema with the <code>generateschema</code> management command</a></h3>
458
460
<p>If your schema is static, you can use the <code>generateschema</code> management command:</p>
<p>If you wish to provide a base <code>AutoSchema</code> subclass to be used throughout your
618
620
project you may adjust <code>settings.DEFAULT_SCHEMA_CLASS</code> appropriately.</p>
621
+
<h3id="grouping-operations-with-tags"><aclass="toclink" href="#grouping-operations-with-tags">Grouping Operations With Tags</a></h3>
622
+
<p>Tags can be used to group logical operations. Each tag name in the list MUST be unique. </p>
623
+
<hr/>
624
+
<h4id="django-rest-framework-generates-tags-automatically-with-the-following-logic"><aclass="toclink" href="#django-rest-framework-generates-tags-automatically-with-the-following-logic">Django REST Framework generates tags automatically with the following logic:</a></h4>
625
+
<p>Tag name will be first element from the path. Also, any <code>_</code> in path name will be replaced by a <code>-</code>.
626
+
Consider below examples.</p>
627
+
<p>Example 1: Consider a user management system. The following table will illustrate the tag generation logic.
628
+
Here first element from the paths is: <code>users</code>. Hence tag wil be <code>users</code></p>
629
+
<table>
630
+
<thead>
631
+
<tr>
632
+
<th>Http Method</th>
633
+
<th>Path</th>
634
+
<th>Tags</th>
635
+
</tr>
636
+
</thead>
637
+
<tbody>
638
+
<tr>
639
+
<td>PUT, PATCH, GET(Retrieve), DELETE</td>
640
+
<td>/users/{id}/</td>
641
+
<td>['users']</td>
642
+
</tr>
643
+
<tr>
644
+
<td>POST, GET(List)</td>
645
+
<td>/users/</td>
646
+
<td>['users']</td>
647
+
</tr>
648
+
</tbody>
649
+
</table>
650
+
<p>Example 2: Consider a restaurant management system. The System has restaurants. Each restaurant has branches.
651
+
Consider REST APIs to deal with a branch of a particular restaurant.
652
+
Here first element from the paths is: <code>restaurants</code>. Hence tag wil be <code>restaurants</code>.</p>
<p>Example 3: Consider Order items for an e commerce company.</p>
675
+
<table>
676
+
<thead>
677
+
<tr>
678
+
<th>Http Method</th>
679
+
<th>Path</th>
680
+
<th>Tags</th>
681
+
</tr>
682
+
</thead>
683
+
<tbody>
684
+
<tr>
685
+
<td>PUT, PATCH, GET(Retrieve), DELETE</td>
686
+
<td>/order_items/{id}/</td>
687
+
<td>['order-items']</td>
688
+
</tr>
689
+
<tr>
690
+
<td>POST, GET(List)</td>
691
+
<td>/order_items/</td>
692
+
<td>['order-items']</td>
693
+
</tr>
694
+
</tbody>
695
+
</table>
696
+
<hr/>
697
+
<h4id="overriding-auto-generated-tags"><aclass="toclink" href="#overriding-auto-generated-tags">Overriding auto generated tags:</a></h4>
698
+
<p>You can override auto-generated tags by passing <code>tags</code> argument to the constructor of <code>AutoSchema</code>. <code>tags</code> argument must be a list or tuple of string.</p>
<p>If you need more customization, you can override the <code>get_tags</code> method of <code>AutoSchema</code> class. Consider the following example:</p>
<p>The schema generator generates an <ahref="openapi-operationid">operationid</a> for each operation. This <code>operationId</code> is deduced from the model name, serializer name or view name. The operationId may looks like "listItems", "retrieveItem", "updateItem", etc..
732
+
The <code>operationId</code> is camelCase by convention.</p>
733
+
<p>If you have several views with the same model, the generator may generate duplicate operationId.
734
+
In order to work around this, you can override the second part of the operationId: operation name.</p>
<p>The previous example will generate the following operationId: "listCustoms", "retrieveCustom", "updateCustom", "partialUpdateCustom", "destroyCustom".
743
+
You need to provide the singular form of he operation name. For the list operation, a "s" will be appended at the end of the operation.</p>
744
+
<p>If you need more configuration over the <code>operationId</code> field, you can override the <code>get_operation_id_base</code> and <code>get_operation_id</code> methods from the <code>AutoSchema</code> class:</p>
<p>Since DRF 3.12, Schema uses the <ahref="openapi-components">OpenAPI Components</a>. This method defines components in the schema and <ahref="openapi-reference">references them</a> inside request and response objects. By default, the component's name is deduced from the Serializer's name.</p>
758
+
<p>Using OpenAPI's components provides the following advantages:
759
+
* The schema is more readable and lightweight.
760
+
* If you use the schema to generate an SDK (using <ahref="openapi-generator">openapi-generator</a> or <ahref="swagger-codegen">swagger-codegen</a>). The generator can name your SDK's models.</p>
<p>You may get the following error while generating the schema:</p>
763
+
<pre><code>"Serializer" is an invalid class name for schema generation.
764
+
Serializer's class name should be unique and explicit. e.g. "ItemSerializer".
765
+
</code></pre>
766
+
767
+
<p>This error occurs when the Serializer name is "Serializer". You should choose a component's name unique across your schema and different than "Serializer".</p>
768
+
<p>You may also get the following warning:</p>
769
+
<pre><code>Schema component "ComponentName" has been overriden with a different value.
770
+
</code></pre>
771
+
772
+
<p>This warning occurs when different components have the same name in one schema. Your component name should be unique across your project. This is likely an error that may lead to an invalid schema.</p>
773
+
<p>You have two ways to solve the previous issues:
774
+
* You can rename your serializer with a unique name and another name than "Serializer".
775
+
* You can set the <code>component_name</code> kwarg parameter of the AutoSchema constructor (see below).
776
+
* You can override the <code>get_component_name</code> method of the AutoSchema class (see below).</p>
777
+
<h4id="set-a-custom-components-name-for-your-view"><aclass="toclink" href="#set-a-custom-components-name-for-your-view">Set a custom component's name for your view</a></h4>
778
+
<p>To override the component's name in your view, you can use the <code>component_name</code> parameter of the AutoSchema constructor:</p>
<h4id="override-the-default-implementation"><aclass="toclink" href="#override-the-default-implementation">Override the default implementation</a></h4>
786
+
<p>If you want to have more control and customization about how the schema's components are generated, you can override the <code>get_component_name</code> and <code>get_components</code> method from the AutoSchema class.</p>
0 commit comments