Skip to content

Operations parameters

Tags

You can group your API operations using tags argument (list[str]).

@api.get("/hello/")
def hello(request, name: str):
    return {"hello": name}


@api.post("/orders/", tags=["orders"])
def create_order(request, order: Order):
    return {"success": True}

Tagged operations may be handled differently by tools and libraries. For example, Swagger UI uses tags to group the displayed operations.

Summary`

Operation Summary

Summary is a human readable name for your operation

By default it's generated by capitalizing your operation function name:

@api.get("/hello/")
def hello(request, name: str):
    return {"hello": name}

Summary`

If you want to override it or translate to other language use summary argument in api decorator

@api.get("/hello/", summary="Say Hello")
def hello(request, name: str):
    return {"hello": name}

Summary`

Operation Description

If you need to provide more information about your operation - use either description argument or docstrings:

@api.post("/orders/", description="Creates an order and updates stock")
def create_order(request, order: Order):
    return {"success": True}

Summary`

When you need to provide long multiline description - you can as well use python docstrings for function definition:

@api.post("/orders/")
def create_order(request, order: Order):
    """
    To create an order please provide:
     - **first_name**
     - **last_name**
     - and **list of Items** *(product + amount)*
    """
    return {"success": True}

Summary`

OpenAPI operationId

OpenAPI operationId is an optional unique string used to identify an operation. If provided, these IDs must be unique among all operations described in your API.

By default Django Ninja sets it to module name + function name

if you want ot set it individually for each operation use operation_id argument:

...
@api.post("/tasks", operation_id="create_task")
def new_task(request):
    ...

And if you want ot override global behavior - you can inherit NinjaAPI instance and override get_openapi_operation_id method

it will be called to each operation, that you defined, so you can set your custom naming logic

from ninja import NinjaAPI

class MySuperApi(NinjaAPI):

    def get_openapi_operation_id(self, operation):
        # here you can access operation ( .path , .view_func, etc) 
        return ...

api = MySuperApi()

@api.get(...)
...

Deprecating Operation

If you need to mark an operation as deprecated without removing it, use the argument deprecated:

@api.post("/make-order/", deprecated=True)
def some_old_method(request, order: str):
    return {"success": True}

It will be marked as deprecated in the json schema an in the interactive docs:

Deprecated

Response output options

There are few arguments that lets you tune responses output:

by_alias

whether field aliases should be used as keys in the response; default False

exclude_unset

whether fields which were not set when creating the schema and have their default values should be excluded from the response; default False

exclude_defaults

whether fields which are equal to their default values (whether set or otherwise) should be excluded from the response; default False

exclude_none

whether fields which are equal to None should be excluded from the response; default False