Автодокументирование¶
QuickAPI построено таким образом, чтобы программисту было предельно просто писать не только сам метод API, но и документацию к нему.
Как вам должно быть известно, в Python любой текст, расположенный в самом начале описания класса или функции - является документацией к нему:
#!/usr/bin/python
# -*- coding: utf-8 -*-
# Copyright 2015 Ivan Ivanov <example@example.com>
"""
Документация к модулю
"""
class MyClass(object):
"""
Документация к классу
"""
def mymethod(self, *args, **kwargs):
""" Документация к методу класса """
return
QuickAPI использует эту особенность, но текст документации должен быть в формате Markdown.
Например:
def my_api_method(request, code, data=None):
"""
### Назначение
Устанавливает что-то из чего-то, и что-нибудь возвращает,
допустим, список лекарств.
### Параметры
1. "code" - код чего-то;
2. "data" - какие-то необязательные данные;
### Ответ
Список добавленных лекарственных средств
```
#!javascript
[
{"title": "Анальгин", "count": 10, "created": "2015-01-01T00:00:00Z" },
{"title": "Аспирин", "count": 20, "created": "2015-01-01T00:00:00Z" },
]
```
"""
now = datetime.now()
data = [
{'title': 'Анальгин', 'count': 10, 'created': now },
{'title': 'Аспирин', 'count': 20, 'created': now },
]
return JSONResponse(data)
И на вашей странице API получится примерно такое описание к методу:
Если же вы создаёте приложение с поддержкой нескольких языков и желаете сделать страницу API тоже мультиязычной, то посмотрите как мы переделаем предыдущий пример, чтобы реализовать отложенный вызов перевода документации:
from django.utils.translation import ugettext_lazy as _
from quickapi.utils.doc import apidoc_lazy, string_lazy
def my_api_method(request, code, data=None):
now = datetime.now()
data = [
{'title': 'Анальгин', 'count': 10, 'created': now },
{'title': 'Аспирин', 'count': 20, 'created': now },
]
return JSONResponse(data)
my_api_method.__doc__ = apidoc_lazy(
header=_("Устанавливает что-то из чего-то, и что-нибудь возвращает, допустим, список лекарств."),
params=string_lazy(
"""
1. "code" - %s;
2. "data" - %s;
""", (_('код чего-то'), _('какие-то необязательные данные'))),
data=string_lazy(
"""
%s
```
#!javascript
[
{"title": "Анальгин", "count": 10, "created": "2015-01-01T00:00:00Z" },
{"title": "Аспирин", "count": 20, "created": "2015-01-01T00:00:00Z" },
]
```
""", _('Список добаленных лекарcтвенных средств')),
)
Конечно, такой подход вносит сумбур в структуру кода, но это того стоит.