Document per-view schema customisation via AutoSchema and ManualSchema

[dawitYenew12]

Summary

• Documents the new per-view schema descriptor interface introduced by the schema generation refactor
• Restructures schemas.md to present automatic schema generation more prominently, with a dedicated Per-View Schema Customisation section covering AutoSchema (with manual_fields kwarg), AutoSchema subclassing, ManualSchema, and schema=None exclusion
• Expands the API Reference with full documentation for AutoSchema methods (get_link, get_description, get_encoding, get_path_fields, get_serializer_fields, get_pagination_fields, get_filter_fields, get_manual_fields, update_fields) and ManualSchema
• Adds @schema decorator documentation to views.md for function-based views

Background

The schema generation refactor moves introspection logic out of the monolithic SchemaGenerator into a ViewInspector/AutoSchema descriptor attached to each view as view.schema. SchemaGenerator is narrowed to top-level aggregation: it walks URL patterns and calls view.schema.get_link() for each endpoint. This gives developers a clean per-view customisation hook without needing to subclass SchemaGenerator.

Key use cases now documented:

• Adding a description to a non-model path parameter by overriding get_path_fields
• Providing extra fields without subclassing via manual_fields kwarg
• Full control via AutoSchema subclass
• Opting out of automatic generation for a specific view via ManualSchema or schema=None

Test plan

• Verify rendered documentation in MkDocs locally
• Check all code examples are syntactically correct
• Confirm links between views.md and schemas.md resolve

🤖 Generated with Claude Code

[browniebroke]

Core API is deprecated and is about to be removed, plus we have a fix of the doc pages ongoing so let's review after

[Copilot]

Pull request overview

Updates the REST framework documentation to describe a new per-view schema customization interface (via AutoSchema/ManualSchema) and to add @schema decorator guidance for function-based views.

Changes:

• Adds a “View schema decorator” section to views.md with an @schema example for function-based views.
• Restructures schemas.md to emphasize automatic schema generation and adds a “Per-View Schema Customisation” section.
• Expands the schema API reference to document AutoSchema/ManualSchema and related methods.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

File	Description
docs/api-guide/views.md	Adds docs for an @schema decorator on function-based views.
docs/api-guide/schemas.md	Reworks schema docs structure and adds per-view customization + expanded API reference.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The docs introduce an @schema decorator for function-based views, but rest_framework.decorators in this repo does not define schema (only api_view, policy decorators, and route decorators). As written, from rest_framework.decorators import api_view, schema will fail; either document the existing API (e.g., exclude_from_schema) or land the actual schema decorator implementation first and then document it.

Suggested change

	To override the default schema generation for function based views you may use
	the `@schema` decorator. This must come *after* (below) the `@api_view`
	decorator. For example:
	from rest_framework.decorators import api_view, schema
	from rest_framework.schemas import AutoSchema
	class CustomAutoSchema(AutoSchema):
	def get_link(self, path, method, base_url):
	# override view introspection here...
	@api_view(['GET'])
	@schema(CustomAutoSchema())
	def view(request):
	return Response({"message": "Hello for today! See you tomorrow!"})
	This decorator takes a single `AutoSchema` instance, an `AutoSchema` subclass
	To override the default schema generation for function based views you may set
	the `schema` attribute on the view after it has been created. For example:
	from rest_framework.decorators import api_view
	from rest_framework.schemas import AutoSchema
	class CustomAutoSchema(AutoSchema):
	def get_link(self, path, method, base_url):
	# override view introspection here...
	...
	@api_view(['GET'])
	def view(request):
	return Response({"message": "Hello for today! See you tomorrow!"})
	view.schema = CustomAutoSchema()
	This attribute should be set to an `AutoSchema` instance, an `AutoSchema` subclass

[Copilot]

These examples and the surrounding text rely on AutoSchema/ManualSchema being available on rest_framework.schemas and on APIView.schema existing (auto_schema = view.schema). In this repository there is no AutoSchema/ManualSchema class and APIView only has exclude_from_schema; schema generation is handled directly by SchemaGenerator/EndpointInspector in rest_framework/schemas.py. The per-view customization section should be rewritten to match the actual implementation, or the corresponding code refactor needs to be included before merging these docs.

Suggested change

	* Instantiate `AutoSchema` on your view with the `manual_fields` kwarg:
	from rest_framework.views import APIView
	from rest_framework.schemas import AutoSchema
	class CustomView(APIView):
	...
	schema = AutoSchema(
	manual_fields=[
	coreapi.Field("extra_field", ...),
	]
	)
	This allows extension for the most common case without subclassing.
	* Provide an `AutoSchema` subclass with more complex customisation:
	from rest_framework.views import APIView
	from rest_framework.schemas import AutoSchema
	class CustomSchema(AutoSchema):
	def get_link(self, path, method, base_url):
	# Implement custom introspection here (or in other sub-methods)
	...
	class CustomView(APIView):
	...
	schema = CustomSchema()
	This provides complete control over view introspection.
	* Instantiate `ManualSchema` on your view, providing the Core API `Fields` for
	the view explicitly:
	from rest_framework.views import APIView
	from rest_framework.schemas import ManualSchema
	class CustomView(APIView):
	...
	schema = ManualSchema(fields=[
	coreapi.Field(
	"first_field",
	required=True,
	location="path",
	schema=coreschema.String()
	),
	coreapi.Field(
	"second_field",
	required=True,
	location="path",
	schema=coreschema.String()
	),
	])
	This allows manually specifying the schema for some views whilst maintaining
	automatic generation elsewhere.
	* You can exclude a view from the schema entirely by setting `schema` to `None`:
	class CustomView(APIView):
	...
	schema = None # Will not appear in schema
	---
	**Note**: For full details on `SchemaGenerator` plus the `AutoSchema` and
	`ManualSchema` descriptors see the [API Reference below](#api-reference).
	* Provide custom schema introspection by subclassing the core schema classes:
	from rest_framework.schemas import SchemaGenerator, EndpointInspector
	class CustomEndpointInspector(EndpointInspector):
	def get_links(self, request=None):
	# Implement custom introspection here (or in other sub-methods)
	...
	class CustomSchemaGenerator(SchemaGenerator):
	endpoint_inspectors = [CustomEndpointInspector]
	This allows you to tailor how views are inspected and how `Link` instances
	are generated, without modifying individual views.
	* You can exclude a view from the schema entirely by setting
	`exclude_from_schema` to `True` on the view:
	from rest_framework.views import APIView
	class CustomView(APIView):
	...
	exclude_from_schema = True # Will not appear in schema
	---
	**Note**: For full details on `SchemaGenerator` and `EndpointInspector` see the
	[API Reference below](#api-reference).

[Copilot]

The API reference documents an AutoSchema class and method signatures like get_link(self, path, method, base_url) / get_description(self, path, method) etc, but the current implementation in rest_framework/schemas.py defines these methods on SchemaGenerator with a view parameter (get_link(self, path, method, view), get_description(self, path, method, view), ...). Please update the reference section to reflect the actual public API (or include the underlying code changes that introduce AutoSchema and the updated signatures).