Apywy 0.0.5

swagger analog

ApyWy - аналог Swagger

Основную проблему, которую решает ApyWy - большое количество времени разработчика для написания схемы (schema) для класса View. В моей версии мы можем использовать обычные питоновские словари для обозначения ожидаемых данныx и ожидаемого ответа.

Пример не настроенной версии apywy:

Пример настроенной версии apywy:

Тут для примера настроен только GET метод.

Установка

pip install apywy

2. Добавляем в settings.INSTALLED_APPS:

INSTALLED_APPS = [
    ...
    'apywy.api',
    ...
]

3. Добавляем в urls.py главного приложения:

path('apywy/', include(('apywy.api.urls', 'apywy.api'), namespace='apywy')),

4. Готово, на главной странице ApyWy - /apywy/ есть вся возможная информация без дополнительных настроек.

Настройка

По умолчанию, все что мы можем узнать для джанго-вьюшки:

• Url-путь до http-метода.
• Док-стринг для вьюшки, а также для всех ее http-методов (get, post, ...).

Но мы можем это исправить, построив ApyWy схему для вьюшки.

Наш файл views.py:

# views.py
class HomePageView(APIView):
    '''
    HomePageView doc string
    '''

    def get(self, request, some_quary):
        'HomePageView.get doc string'

        if some_quary == 'some value':
            return Response({'ANSWER': 'GET-INVALID-RESULT'}, status=status.HTTP_500_INTERNAL_SERVER_ERROR)
        return Response({'ANSWER': 'GET-RESULT'}, status=status.HTTP_200_OK)

    def post(self, request):
        'HomePageView.post doc string'
        return Response({'ANSWER': 'POST-RESULT'}, status=status.HTTP_201_CREATED)

• Создаем файл apywy_schemas.py (имя не важно)

# apywy_schemas.py
from apywy.fields import StatusField, MethodField, RequestDataField
from apywy.schema import Schema

from apywy.constants.const import Constant


class HomePageSchema(Schema):
    class GET(MethodField):

        HTTP_200 = StatusField(expected_response_data=Constant({'ANSWER': 'GET-RESULT'}))

        HTTP_500 = StatusField(expected_response_data=Constant({'ANSWER': 'GET-INVALID-RESULT'}))

• Навешиваем эту схему на view:

# views.py
...
from apywy.decorators import set_apywy_schema

from .apywy_schemas import HomePageSchema


@set_apywy_schema(HomePageSchema)
class HomePageView(APIView):
    ...

Итог, для метода get мы получили расширенную информацию.

• Добавим информацию про post

# apywy_schemas.py
...

class HomePageSchema(Schema):
    ...

    class POST(MethodField):

        HTTP_201 = StatusField(expected_response_data=Constant({'ANSWER': 'POST-RESULT'}))

        class META:
            expected_request_data = RequestDataField(Constant({'data': 'some data here'}))

По итогу, конечный вариант нашей схемы:

# apywy_schemas.py
from apywy.fields import StatusField, MethodField, RequestDataField
from apywy.schema import Schema

from apywy.constants.const import Constant


class HomePageSchema(Schema):
    class GET(MethodField):

        HTTP_200 = StatusField(expected_response_data=Constant({'ANSWER': 'GET-RESULT'}))

        HTTP_500 = StatusField(expected_response_data=Constant({'ANSWER': 'GET-INVALID-RESULT'}))

    class POST(MethodField):

        HTTP_201 = StatusField(expected_response_data=Constant({'ANSWER': 'POST-RESULT'}))

        class META:
            expected_request_data = RequestDataField(Constant({'data': 'some data here'}))

---

По умолчанию на главной странице мы видим вьюшки до всех путей, кроме тех, которые относятся к неймспейсам:

('apywy', 'admin')

Если вы хотите игнорировать дополнительные неймспейсы, то укажите это в settings.NAMESPACES_TO_IGNORE:

NAMESPACES_TO_IGNORE = ()  # значение по умолчанию

NAMESPACES_TO_IGNORE = ('app', )  # игнорировать namespace с именем "app"

NAMESPACES_TO_IGNORE = ('*', )  # игнорировать все неймспейсы

FAQ:

1. Можно ли указать query параметр для запроса в схеме?
2. Можно ли указать сразу несколько ожидаемых результатов от фронта/бекенда в схеме для одного http статуса?

(1) и (2), да можно, ниже представлены различные варианты, которые поддерживает apywy:

# apywy_schemas.py
from apywy.fields import StatusField, MethodField, RequestDataField
from apywy.schema import Schema

from apywy.constants.const import ListOfConstants, Constant


class HomePageSchema(Schema):
    class GET(MethodField):

        # пример, когда для метода есть единственные данные, независящие от аргумента
        HTTP_200 = StatusField(expected_response_data=Constant({'ANSWER': 'GET-RESULT'}))

        # пример, что и выше, но только с комментарием
        HTTP_300 = StatusField(
            expected_response_data=Constant({'ANSWER': 'GET-RESULT FROM 300'}, comment='some comment')
        )

        # пример, когда для метода есть единственные данные, но мы также хотим задокументировать query паметр
        HTTP_400 = StatusField(
            expected_response_data=Constant({'ANSWER': 'GET-RESULT FROM 400'}, query_arg={'some query': 1})
        )

        # пример, когда для одного статуса может соответствовать множество данных
        HTTP_500 = StatusField(
            expected_response_data=ListOfConstants(
                Constant(
                    expected_data={'ANSWER': 'GET-RESULT FROM 500'},
                    comment='some another comment with list of constants'
                ),
                Constant(
                    expected_data={'ANSWER': 'GET-RESULT FROM 500'},
                    query_arg={
                        'some query 1': '1',
                        'some another query 2': 'blabla',
                    },
                    comment='some comment here'
                ),
            )
        )

        class META:
            # все что относится к работе со статусами распространяется и на request данные
            expected_request_data = RequestDataField(
                ListOfConstants(
                    Constant(expected_data={'some data 1': 'data1'}),
                    Constant(expected_data={'some another data 2': 'data2'}, query_arg={
                        'title': 'some title',
                        'book_id': '10'
                    }),
                )
            )

TODO:

• Рефакторить index.js