Skip to content

Operations parameters

The following parameters interact with the how the OpenAPI schema (and docs) are generated.


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

def hello(request, name: str):
    return {"hello": name}"/orders/", tags=["orders"])
def create_order(request, order: Order):
    return {"success": True}

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


Router tags

You can use tags argument to apply tags to all operations declared by router:

api.add_router("/events/", events_router, tags=["events"])

# or using constructor: 

router = Router(tags=["events"])


A human-readable name for your operation.

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

def hello(request, name: str):
    return {"hello": name}


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

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



To provide more information about your operation, use either the description argument or normal Python docstrings:"/orders/", description="Creates an order and updates stock")
def create_order(request, order: Order):
    return {"success": True}


When you need to provide a long multi line description, you can use Python docstrings for the function definition:"/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}



The 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 to set it individually for each operation, use the operation_id argument:

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

If you want to override global behavior, you can inherit the NinjaAPI instance and override the get_openapi_operation_id method.

It will be called for each operation that you defined, so you can set your custom naming logic like this:

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()



Mark an operation as deprecated without removing it by using the deprecated argument:"/make-order/", deprecated=True)
def some_old_method(request, order: str):
    return {"success": True}

It will be marked as deprecated in the JSON Schema and also in the interactive OpenAPI docs:



If you need to include/exclude some operation from OpenAPI schema use include_in_schema argument:"/hidden", include_in_schema=False)
def some_hidden_operation(request):

Response output options

There are a few arguments that lets you tune response's output:


Whether field aliases should be used as keys in the response (defaults to False).


Whether fields that were not set when creating the schema, and have their default values, should be excluded from the response (defaults to False).


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


Whether fields which are equal to None should be excluded from the response (defaults to False).


Allows you to set api endpoint url name (using django path's naming)"/tasks", url_name='tasks')
def some_operation(request):

# then you can get the url with


See the Reverse Resolution of URLs guide for more details.