Документация API Swagger

Я видел чванливую документацию по Flask и Джанго. В Flask я могу разработать и задокументировать свой API от руки (указать, какие поля являются обязательными, необязательными и т. д. в разделах параметров).

Вот как мы работаем во Flask

class Todo(Resource):
    "Describing elephants"
    @swagger.operation(
        notes='some really good notes',
        responseClass=ModelClass.__name__,
        nickname='upload',
        parameters=[
            {
              "name": "body",
              "description": "blueprint object that needs to be added. YAML.",
              "required": True,
              "allowMultiple": False,
              "dataType": ModelClass2.__name__,
              "paramType": "body"
            }
          ],
        responseMessages=[
            {
              "code": 201,
              "message": "Created. The URL of the created blueprint should be in the Location header"
            },
            {
              "code": 405,
              "message": "Invalid input"
            }
          ]
        )

Я могу выбрать, какие параметры включать, а какие нет. Но как реализовать то же самое в Django? Документ Django-Swagger совсем нехорошо. Моя главная проблема заключается в том, как мне написать свой raw-json в Django.

В Django он автоматизирует это, что не позволяет мне настраивать мой json. Как реализовать то же самое в Django?

Вот файл models.py

class Controller(models.Model):
    id = models.IntegerField(primary_key = True)
    name = models.CharField(max_length = 255, unique = True)
    ip = models.CharField(max_length = 255, unique = True)
    installation_id = models.ForeignKey('Installation')

сериализаторы.py

class ActionSerializer(serializers.ModelSerializer):
    class Meta:
        model = Controller
        fields = ('installation',)

urls.py

from django.conf.urls import patterns, url
from rest_framework.urlpatterns import format_suffix_patterns
from modules.actions import views as views

urlpatterns = patterns('',
    url(r'(?P<installation>[0-9]+)', views.ApiActions.as_view()),
)

views.py

class ApiActions(APIView):

    """
    Returns controllers List
    """

    model = Controller
    serializer_class = ActionSerializer 

    def get(self, request, installation,format=None):

        controllers = Controller.objects.get(installation_id = installation)
        serializer = ActionSerializer(controllers)
        return Response(serializer.data)

Мои вопросы

1) Если мне нужно добавить поле, скажем, xyz, которого нет в моих моделях, как мне его добавить?

2) Тихо, аналогично 1-му, если мне нужно добавить поле, которое принимает значения ч/б 3 предоставленных значения, т.е. раскрывающийся список. как добавить?

3) Как добавить необязательное поле? (поскольку в случае запроса PUT я мог бы обновить только 1 поле, а остальные оставить его пустым, что означает поле optional).

4) Также как добавить поле, которое принимает строку json, как этот API делает?

Спасибо

Я могу делать все эти вещи во Flask, жестко запрограммировав свой API. Но в Django он автоматизируется из моих моделей, что (как я считаю) не дает мне доступа к настройке моего API. Во Flask мне нужно просто написать свой API руками, а потом интегрировать с Swagger. Есть ли то же самое в Django?

Например, мне просто нужно добавить следующий json в мой код Flask, и он ответит на все мои вопросы.

# Swagger json:
    "models": {
        "TodoItemWithArgs": {
            "description": "A description...",
            "id": "TodoItem",
            "properties": {
                "arg1": { # I can add any number of arguments I want as per my requirements.
                    "type": "string"
                },
                "arg2": {
                    "type": "string"
                },
                "arg3": {
                    "default": "123",
                    "type": "string"
                }
            },
            "required": [
                "arg1",
                "arg2" # arg3 is not mentioned and hence 'opional'
            ]
        },

python django flask rest swagger
person python-coder    schedule 30.01.2014    source источник
comment
этот ответ может быть полезно для вас   -  person Marosinho    schedule 18.08.2016

Ответы (1)


arrow_upward
0
arrow_downward

Будет ли это работать:

class TriggerView(APIView):
    """
    This text is the description for this API
        mykey -- My Key parameter
    """

    authentication_classes = (BasicAuthentication,)
    permission_classes = (IsAuthenticated,)

    def post(self, request, format=None):
        print request.DATA
        return Response(status=status.HTTP_202_ACCEPTED)

POST-запрос:

Authorization:Basic YWRtaW46cGFzcw==
Content-Type:application/json

{"mykey": "myvalue"}
person mariodev    schedule 30.01.2014
comment
Спасибо за ответ. Как мне выполнить put запрос? Что я сейчас делаю, так это включаю выбранные поля в класс Serializer, например class ActionSerializer(serializers.ModelSerializer): class Meta: model = Controller fields = ('installation_id','ip','xyz','abc'), и таким образом перечислены все поля, но ни одно из них не является необязательным, каждое поле обязательно. 1) Как добавить необязательное поле? 2) Также как добавить поле, которое принимает строку json? 3) Как добавить поле, которое принимает значения ч/б из 3 предоставленных значений, т. е. раскрывающееся меню? Заранее спасибо. - person python-coder; 30.01.2014
comment
@python-coder Пожалуйста, укажите все подробности в своем вопросе, определение модели, сериализатор, представление, URL-адреса.. - person mariodev; 30.01.2014
comment
Пожалуйста, смотрите мой отредактированный вопрос. Я добавил свои модели, сериализаторы, URL-адреса и представления. - person python-coder; 31.01.2014