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

In case you do not need to display interactive documentation - set docs_url argument to None

api = NinjaAPI(docs_url=None)

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 OpenaAPI - create a class inherited from DocsBase and overwrite render_page method:

form ninja.openapi.docs import DocsBase

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

...

api = NinjaAPI(docs=MyDocsViewer())