django-rest-swagger: how to group endpoints?

Question:

I am using Django REST Framework and django-rest-swagger library for building an API endpoints. I would like to group some API urls by custom attribute instead of URL.

For example I have API endpoints and would like to group them by functions:

# task list management

GET /api/tasks/known  - get known tasks list with their parameters
GET /api/tasks  - get last tasks list with their statuses

# Tasks by ID management

GET /api/task/12345  - get task result/status
DELETE /api/task/12345  - Revoke task

# Task by name management:
# MyTask123

GET /api/tasks/MyTask123 - get task info (parameters, etc)
POST /api/tasks/MyTask123 - async start new task

# MySuperShinyTask777

GET /api/tasks/MySuperShinyTask777 - get task info (parameters, etc)
POST /api/tasks/MySuperShinyTask777 - async start new task

# scheduled tasks management

GET /api/tasks/scheduled - get list of scheduled tasks

# manage exact scheduled tasks

POST /api/tasks/scheduled/MyTask123 - schedule new task
GET /api/tasks/scheduled/12345 - get scheduled task details
PUT /api/tasks/scheduled/12345 - change scheduled task
DELETE /api/tasks/scheduled/12345 - delete scheduled task

So I would like to show them grouped by roles. Now they grouped all only ‘/api/’ and that’s it.

In urls.py I include it like this:

url(r'^api/', include('api.urls'), name='my-api-root'),

How can I do custom grouping for django-rest-swagger?

Asked By: baldr

||
Source

Answers:

You can have a urls.py in your tasks app (I assume there is one), and declare them in your /tasks urls.

One of this for each of your endpoints

url(r'^ tasks/(?P<task_id>w+)$',
    YourTaskView,
    name='task'),

And this in your api root urls.py

url(r'^api/', include('api.tasks.urls'), name='my-api-root'),

BUT, looks like you could use DRF routers

Answered By: Thiago Charão

I see that people keep visiting this question and upvote it. This means the question is actual. I can describe what I ended up with with similar task recently.

I created a YAML representation of API endpoints according to OpenAPI spec. I had to keep the same API endpoints on the backend too and this is a drawback as this is not auto-generated docs.

I installed Swagger-UI with docker and it uses my YAML spec to represent Swagger page.

It is easy to separate endpoints by custom groups and even have one endpoint in two groups.

Answered By: baldr

What about that setting?

SPECTACULAR_SETTINGS = {
    'SCHEMA_PATH_PREFIX': '/api/tasks',
}

Or, not tested, but it seems that you can use the tags param from @extend_schema to customize the grouping of the endpoints.

Answered By: mailivres