django-rest-swagger wie man die APIs dokumentiert

Question

Ich benutze jetzt DRS für meine einfache django REST APIs und obwohl es nicht perfekt ist, war es eine große Bibliothek bisher. Aber mit ein paar Probleme

Ich bin mit

django-rest-swagger==2.0.3 

Und mein api-doc sieht wie folgt aus

Ausgabe # 1: Ich kann nicht einen Weg finden, einige hinzufügen Dokumentation habe ich versucht, YAML unter meine klassenbasierten Viewset-Action-Methoden zu setzen, die nicht funktionieren. Setzen Sie DocString direkt unter ViewSet-Klasse, kein Glück. Dann sah ich, dass in der neuesten DRS-Version, 2.0 Änderung erwähnte YAML Docstring veraltet ist.

Wie stelle ich so etwas wie 1. Endpoint kurze Beschreibung 2. Parameterbeschreibung und wahrscheinlich einer Probe Format

Issue # 2: Wie kann ich festlegen, welche Parameter ist obligatorisch.

Zum Beispiel, ich habe eine Aktion in meinem UserViewSet

@detail_route(methods=['post'], url_path='set-password') 
@AssertInRequestBody(['password']) 
def set_password(self, request, pk): 
    """ 
    set user password 
    """ 
    user = User.objects.get(pk=pk) 
    json_data = get_json_data(request) 
    user.set_password(json_data['password']) 
    user.save() 
    return DefaultResponse(_('Successfully set password for user %s' 
          % user.email), status.HTTP_200_OK) 

Und ich will es eine POST-Operation sein, und es wird ein Passwort in der Anfrage Körper sein. Ich kann keinen Weg finden, das zu dokumentieren.

Dies gilt für andere Operationen, ich denke, jetzt gerade DRS ist einfach auf die Modelldefinition und Serializer-Definition zu bestimmen, welche Parameter obligatorisch ist, was nicht ganz sinnvoll für mich ist.

Ich denke, dass DRS einige Arten von Dekoratoren zur Verfügung stellen sollte, so dass wir einfach eine entsprechende Dokumentation zu einer Aktionsmethode hinzufügen können.

Aber vielleicht bin ich falsch, bitte helfen, wenn DRS solche Funktionen bietet.

Danke,

Answer 1

Da Sie einen Beitrag, tun den Endpunkt Kurzbeschreibung hinzuzufügen, ist, was ich

def set_password(self, request, pk): 
    """ 
    create: 
     set user password 
    """ 
    ... 

oder in Ihrem UserViewSet Klasse tun:

class UserViewSet(...) 
    """ 
    set_password: 
     set user password 
    """ 

Das kann die Frage beantworten 1

Answer 2

Vielleicht ist das so spät, aber nur für einige Hilfe, dieses Dokument e xplains django rest swagger 2 integration schritt für schritt: Django Rest Swagger 2 comprehensive documentation