Skip to content

# API Docs

## OpenAPI docs

Once you configured your Ninja API and started runserver - go to http://127.0.0.1:8000/api/docs

You will see the automatic, interactive API documentation (provided by the OpenAPI / Swagger UI

## CDN vs staticfiles

You are not required to put django ninja to `INSTALLED_APPS`. In that case the interactive UI is hosted by CDN.

To host docs (Js/css) from your own server - just put "ninja" to INSTALLED_APPS - in that case standard django staticfiles mechanics will host it.

## Switch to Redoc

    from ninja import Redoc

    api = NinjaAPI(docs=Redoc())

Then you will see the alternative automatic documentation (provided by Redoc).

## Changing docs display settings

To set some custom settings for Swagger or Redocs you can use `settings` param on the docs class

    from ninja import Redoc, Swagger

    api = NinjaAPI(docs=Swagger(settings={"persistAuthorization": True}))
    ...
    api = NinjaAPI(docs=Redoc(settings={"disableSearch": True}))

Settings reference:

- Swagger configuration
- Redoc configuration

## Hiding docs

### Hiding the interactive docs viewer

To hide only the interactive documentation UI (Swagger or Redoc) while keeping the OpenAPI schema accessible, set `docs_url` to `None`:

    api = NinjaAPI(docs_url=None)

This disables the `/docs` endpoint but the OpenAPI schema remains available at `/openapi.json`. This is useful when you want to:

- Disable the interactive UI but keep the schema for API clients or code generators
- Use external documentation tools that consume the OpenAPI spec

### Disabling the OpenAPI schema endpoint

To disable the OpenAPI schema endpoint, set `openapi_url` to `None`:

    api = NinjaAPI(openapi_url=None)

This disables the `/openapi.json` endpoint. Since the docs viewer depends on the OpenAPI schema, this also disables the docs viewer - no documentation URLs will be registered.

### Summary

Configuration | `/openapi.json` | `/docs` | Use Case
--- | --- | --- | ---
Default | Available | Available | Development
`docs_url=None` | Available | Hidden | Hide UI, keep schema for clients
`openapi_url=None` | Hidden | Hidden | Completely hide all documentation

## Protecting docs

To protect docs with authentication (or decorate for some other use case) use `docs_decorator` argument:

    from django.contrib.admin.views.decorators import staff_member_required

    api = NinjaAPI(docs_decorator=staff_member_required)

## Extending OpenAPI Spec with custom attributes

You can extend OpenAPI spec with custom attributes, for example to add `termsOfService`

    api = NinjaAPI(
       openapi_extra={
           "info": {
               "termsOfService": "https://example.com/terms/",
           }
       },
       title="Demo API",
       description="This is a demo API with dynamic OpenAPI info section"
    )

## Resolving the doc's url

The url for the api's documentation view can be reversed by referencing the view's name `openapi-view`.

In Python code, for example:

    from django.urls import reverse

    reverse('api-1.0.0:openapi-view')

    >>> '/api/docs'

In a Django template, for example:

    <a href="{% url 'api-1.0.0:openapi-view' %}">API Docs</a>

    <a href="/api/docs">API Docs</a>

## Creating custom docs viewer

To create your own view for OpenAPI - create a class inherited from DocsBase and overwrite `render_page` method:

    from ninja.openapi.docs import DocsBase

    class MyDocsViewer(DocsBase):
        def render_page(self, request, api):
            ... # return http response

    ...

    api = NinjaAPI(docs=MyDocsViewer())

## Using a custom favicon

The django-ninja OpenAPI docs contain a default favicon, the ninja star. To use your own, overwrite the `ninja/favicon.html` django template.

    <!-- templates/ninja/favicons.html -->
    {% load static %}

    {% block favicons %}
        <link rel="icon" type="image/png" href="{% static 'path/to/your/favicon.png' %}">
    {% endblock %}

for more information, see the Django documentation on overriding templates.