Автодокументирование

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 получится примерно такое описание к методу:

../_images/autodoc001.png

Если же вы создаёте приложение с поддержкой нескольких языков и желаете сделать страницу 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твенных средств')),
)

Конечно, такой подход вносит сумбур в структуру кода, но это того стоит.