Customize the OpenAPI Schema#

Restly’s generated routes are ordinary FastAPI path operations, so everything OpenAPI-related composes the FastAPI way. This page maps the customization points.

Per-view metadata#

To apply OpenAPI metadata across a whole view, set the tags, responses, and dependencies class attributes; they exist on every view and apply to all of its routes, generated and custom:

@fr.include_view(app)
class InvoiceView(fr.AsyncRestView):
    prefix = "/invoices"
    tags = ["billing"]
    responses = {402: {"description": "Payment required"}}
    model = Invoice
    schema = InvoiceRead

Per-route metadata on custom routes#

To document a custom route, pass keyword arguments to its route decorator; the decorators forward them to FastAPI’s add_api_route(), so custom actions document themselves like any FastAPI endpoint:

    @fr.post(
        "/{id}/publish",
        status_code=200,
        summary="Publish an article",
        responses={409: {"description": "Already published"}},
    )
    async def publish(self, id: int): ...

Change a generated route’s documented contract#

A generated route’s response_model (and therefore its documented schema) comes from the view’s schema family. To document (and return) a different shape on one verb, replace that endpoint method with your own decorator and response_model; see Response Envelopes and List Metadata, a different schema for the list endpoint, and replacing an endpoint method.

Routes removed with exclude_routes disappear from the schema entirely.

Resource references (x-resource-ref)#

Reference fields are annotated in the generated spec so clients and generators can see which resource a scalar id points at. Schema fields declared with fr.MustExist[int, Model] (a foreign-key column) or fr.IDRef[Model] / fr.IDSchema[Model] (a relationship) carry the vendor extension x-resource-ref: "<resource-name>". The reference styles are covered in Work with Foreign Keys and Relationships.

There is a known limit: views included on an APIRouter rather than the app currently lose these annotations.

See also#