Skip to content

Operations parameters

Tags

You can group your API operations using the 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 various tools and libraries. For example, the Swagger UI uses tags to group the displayed operations.

Summary`

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"])

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 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}

Summary`

Operation: Description

If you need to provide more information about your operation, use either the description argument or normal Python 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 a long multi line description, you can use Python docstrings for the 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

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:

...
@api.post("/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()

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

Operation: Deprecated

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

@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 and also in the interactive OpenAPI docs:

Deprecated

Response output options

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

by_alias

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

exclude_unset

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

exclude_defaults

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

exclude_none

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

Include/Exclude operation from schema(docs)

If you need to exclude some operation from OpenAPI schema use include_in_schema argument:

@api.post("/hidden", include_in_schema=False)
def some_hiden_operation(request):
    pass

url_name

Allows you to set api endpoint url name (using django path's naming)

@api.post("/tasks", url_name='tasks')
def some_operation(request):
    pass

# then you can get the url with

reverse('api-1.0.0:tasks')