[Python] Swagger API documentation

I saw swagger documentation of Flask and Django. In Flask I can design and document my API hand-written.(Include which fields are required, optional etc. under parameters sections).

Here's how we do in 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"
}
]
)


I can chose which parameters to include, and which not. But how do I implement the same in Django? Django-Swagger Document in not good at all. My main issue is how do I write my raw-json in Django.

In Django it automates it which does not allows me to customize my json. How do I implement the same kind of thing on Django?

Here is models.py file

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')


serializers.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)


My questions are

1) If I need to add a field say xyz, which is not in my models how do I add it?

2) Quiet similar to 1st, If i need to add a field which accepts values b/w 3 provided values,ie a dropdown. how do I add it?

3) How I add an optional field? (since in case of PUT request, I might only update 1 field and rest leave it blank, which means optional field).

4) Also how do I add a field that accepts the json string, as this api does?

Thanks

I can do all of these things in Flask by hardcoding my api. But in Django, it automates from my models, which does not(as I believe) gives me the access to customize my api. In Flask, I just need to write my API with hands and then integrate with the Swagger. Does this same thing exist in Django?

Like I just need to add the following json in my Flask code and it will answer all my questions.

# 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'
]
},

Continue reading...