[PYTHON] So generieren Sie automatisch ein API-Dokument mit dem Django REST-Framework und POST vom Dokumentbildschirm

In diesem Artikel wird erläutert, wie das API-Dokument beim Erstellen einer API mit dem Django REST-Framework automatisch generiert wird (Erläuterung der Verwendung usw.).

Schritt 0: DRF (Django REST Framework)

Dieses Mal verwende ich ** Version: 3.10.3 **. Die neueste Version (September 2020) ist ** Version: 3.11.1 **.

Schritt 1: Installieren Sie zusätzliche Pakete

Installieren Sie die für die automatische API-Dokumentation erforderlichen Pakete.

pip install coreapi
pip install Pygments
pip install Markdown

Schritt 2: Definieren Sie eine Dokumentseite in urls.py

Für urls.py im App-Ordner, der die Basis der Django-App bildet

from rest_framework.documentation import include_docs_urls

So aktivieren Sie die Verwendung von "include_docs_urls ()".

Setzen Sie dann path (" docs / "...) in urls.py der Anwendung wie folgt.

...

from rest_framework.documentation import include_docs_urls

urlpatterns = [
    path("admin/", admin.site.urls),
    path("docs/", include_docs_urls(title='API Document')),
    ...

Wenn Sie jetzt auf / docs zugreifen (z. B. http: // localhost: 8000 / docs /), wird die API-Dokumentationsseite wie unten gezeigt angezeigt.

** * Fehler Gegenmaßnahmen ** Wenn Sie die Dokumentenseite besuchen, hat das Objekt "autoschema" kein Attribut "get_link" django " Wenn der Fehler angezeigt wird,

In der Datei settingsts.py des Anwendungsordners wie folgt 'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.coreapi.AutoSchema' Wird hinzugefügt werden.

...
REST_FRAMEWORK = {
    ...
    'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.coreapi.AutoSchema'
}

Dies geschieht, wenn Sie DRF Version 3.10 oder höher verwenden.

(Referenz) Django REST Framework 3.10 https://www.django-rest-framework.org/community/3.10-announcement/

Schritt 3: Lesen des Dokumentbildschirms

Unten links auf dem Bildschirm befinden sich Menüs mit den Namen Authentifizierung und Quellcode.

[3.1] Sie können sich anmelden, indem Sie die Authentifizierung bereitstellen. Wenn Sie sich hier anmelden, können Sie die API von diesem Dokumentbildschirm aus aufrufen, während Sie angemeldet sind. (Wie Sie auf die API zugreifen, wird im späteren Abschnitt erläutert.)

[3.2] Der Quellcode verwendet Coreapi auf der rechten Seite des Bildschirms

• shell
• Javascript
• Python

Sie können den Implementierungscode für jede API anzeigen

** * Fehler Gegenmaßnahmen ** Wenn Sie aus irgendeinem Grund zum normalen API-Bildschirm anstelle des Dokumentbildschirms wechseln und über den Django Admin-Bildschirm auf Dokumente zugreifen, während Sie einmal angemeldet sind, wird der Dokumentbildschirm angezeigt (Ursache unbekannt).

Schritt 3: Bereiten Sie die API-Beschreibung vor

Derzeit gibt es keine Erklärung für den Vorgang für jede API. (Da {id} in der URL nur zum Lesen verwendet wird, wird "id" automatisch als erforderlicher Parameter beschrieben.)

Fügen Sie hier eine Beschreibung jeder API hinzu.

Wenn Sie einen Kommentar für die "ViewSet-Klasse" schreiben, die viewssets.ViewSet usw. in views.py der entsprechenden App erbt, wird dieser als Erläuterung der API in den Dokumenten wiedergegeben.

Zum Beispiel viewssets.ViewSet Da die API in jede Klassenklasse unterteilt ist, erstellen, abrufen, aktualisieren, teilweise aktualisieren, zerstören, Beschreiben Sie die API-Beschreibung für jede dieser Klassen.

Die Implementierung ist wie folgt.

class DatasetViewset(viewsets.ViewSet):
    """
    list:
Informationen für alle Datensätze abrufen.

    create:
Erstellen Sie neue Datensatz-Metainformationen.

    retrieve:
Holen Sie sich die Informationen des einzelnen Datensatzes, der von pk angegeben wird.
　　　
    """

    def list(self, request):
・ ・ ・

Anschließend wird die folgende Beschreibung zu den Dokumenten der API hinzugefügt.

Wenn Sie die Erklärung der API beschreiben, wird am Ende dieses Artikels erläutert, welche Art von Inhalt beschrieben werden soll.

Schritt 4: Sie können die API aufrufen

Sie können die API von diesem Dokumentbildschirm aus aufrufen. Wenn Sie in der Mitte des obigen Bildschirms auf die grüne Schaltfläche "Interagieren" klicken, wird der Bildschirm zum Aufrufen der API angezeigt.

Dies ist für GET-Systeme in Ordnung, aber die Erstellungs- (POST) und PUT-Systeme sind derzeit unvollständig.

In der vorherigen Abbildung werden die zum Erstellen und Einfügen erforderlichen Parameter nicht beschrieben, was zur Erläuterung der API nicht ausreicht.

Selbst wenn ich beim Erstellen auf die Schaltfläche "Interagieren" klicke, wird der unten gezeigte Bildschirm angezeigt und ich kann die zu postenden Parameterwerte nicht schreiben.

Es gibt verschiedene Möglichkeiten, die Erklärung dieses POST-Typs und der PUT-Typ-API vorzubereiten, damit Sie auf die POST-API zugreifen können.

Das Django REST Framework Schema ist die Erklärung. https://www.django-rest-framework.org/api-guide/schemas/

Ein einfacher Weg ist zu def get_serializer(self): Der Code von wird in der ViewSet-Klasse und für jede Methode beschrieben. Es ist eine Strategie, den in dieser Methode verwendeten Serializer zu beschreiben und umzuleiten.

class DatasetViewset(viewsets.ViewSet):
    """
    list:
Informationen für alle Datensätze abrufen.

    create:
Erstellen Sie neue Datensatz-Metainformationen.

    retrieve:
Holen Sie sich die Informationen des einzelnen Datensatzes, der von pk angegeben wird.
    """

    def get_serializer(self):
        """Für die API-Dokumentation"""
        if self.action is "create":
            return DatasetCreateInputSerializer()
        elif self.action is "update":
            return DatasetUpdateMetadataInputSerializer()

    def list(self, request):
・ ・ ・

Anschließend ändert sich der Dokumentbildschirm wie folgt.

Die obige Abbildung ist etwas schwer zu erkennen, aber beim Erstellen und Aktualisieren sind die für jede API erforderlichen Parameter vorhanden.

Das Letzte, worüber Sie sich Sorgen machen müssen, ist, dass die Beschreibung der einzelnen Parameter keine Beschreibung enthält.

Um die Beschreibung zu beschreiben und die in dieser API verwendeten Argumente richtig zu erklären, gehen Sie zu models.py

name = models.CharField(blank=False, max_length=100, unique=True, help_text="Projektname")

Beschreiben Sie die Erklärung im Argument "help_text" wie in.

Wenn Sie in Serializers eine modellunabhängige Klasse erstellt haben. Serializer in Serializers beschreiben Sie diese im Argument "help_text" dieses Felds.

Der Dokumentbildschirm sieht dann wie folgt aus, und die Beschreibung jedes Parameters wird in die Beschreibung eingegeben, z. B. "Datensatzname".

Und wenn es sich in diesem Zustand befindet (def get_serializer () wird in der ViewSet-Klasse beschrieben und der in dieser Methode verwendete Serializer wird für jede Methode angegeben),

Wenn Sie in der Mitte des Bildschirms auf die grüne Schaltfläche "Interagieren" klicken, wird der Bildschirm zum Aufrufen der API mit den angezeigten Argumenten angezeigt.

Jetzt können Sie diese API POSTEN, indem Sie den Wert jedes Parameters eingeben, wenn Sie auf die API auf der linken Seite klicken und unten rechts auf "Anfrage senden" klicken.

Schritt 5: Was Sie in der API-Beschreibung beschreiben möchten

Abschließend werde ich erklären, was Sie in der Erklärung der API beschreiben sollen.

** Was wichtig ist, ist der mitfühlende Wunsch, eine API-Dokumentation zu erstellen, die aus Sicht des Benutzers, der die API verwendet, leicht zu verstehen und zu verstehen ist. ** ** **

Der Inhalt, den Sie beschreiben möchten, hängt stark davon ab, ob die API nur innerhalb des Systems und nur vom Entwicklungsteam verwendet wird oder ob die API nach außen offengelegt wird.

wie auch immer,

• Zusammenfassung der API-Operation (Ergebnisse erstellt)
• Details der API-Operation (Wenn ein Link zum UML-Diagramm vorhanden ist, beschreiben Sie den Link) --HTTP-Antwortstatuscode in normaler Form der API und zurückgegebener Inhalte --Argumente (Name, Beschreibung, erforderlich, Typ)
• Abnormaler HTTP-Antwortstatuscode und zurückgegebener Inhalt

Ich will es.

Für andere Inhalte, die in der API beschrieben werden sollen

● Buch "Web API Design" https://www.amazon.co.jp/dp/4798167010/

● Googles API-Designhandbuch https://cloud.google.com/apis/design

● MS API Design Guide https://docs.microsoft.com/ja-jp/azure/architecture/best-practices/api-design

● API-Stilbuch http://apistylebook.com/

Ich denke, es ist eine gute Idee, zu vergleichen, wie viel Sie mit Ihrem eigenen Team schreiben, unter Bezugnahme auf das oben Gesagte.

Auf diese Weise werden API-Dokumente mit dem Django REST Framework & POST automatisch über den Dokumentbildschirm generiert.

Bemerkungen

** 【Übermittlung von Informationen】 ** Zusätzlich zu den Eindrücken der Bücher, die ich lese, veröffentliche ich Artikel und Websites auf Twitter, die ich für IT / KI und Business / Management interessant finde. Wenn Sie Informationen zu diesen Feldern sammeln möchten, folgen Sie uns bitte ♪ (Es gibt viele Informationen aus Übersee)

Yutaro Ogawa @ISID_AI_team https://twitter.com/ISID_AI_team

** [Andere] ** Das von mir geleitete "AI Technology Department Development Team" sucht Mitglieder. Wenn Sie interessiert sind Diese Seite Danke ♪

** [Sokumen-Kun] ** Wenn Sie sich plötzlich bewerben möchten, haben wir ein ungezwungenes Interview mit "Sokumen-kun". Bitte benutzen Sie dies auch ♪ https://sokumenkun.com/2020/08/17/yutaro-ogawa/

[Haftungsausschluss] Der Inhalt dieses Artikels selbst ist die Meinung / Übermittlung des Autors, nicht die offizielle Meinung des Unternehmens, zu dem der Autor gehört.

Weitere Referenzen in diesem Artikel

• Built-in API documentation
• [Django Rest Framework zum Erstellen einer Website für Datenwettbewerbe](https://nykergoto.hatenablog.jp/entry/2019/12/22/%E3%83%87%E3%83%BC%E3%82%BF%E3% 82% B3% E3% 83% B3% E3% 83% 9A% E3% 82% B5% E3% 82% A4% E3% 83% 88% E3% 82% 92% E4% BD% 9C% E3% 82% 8B_drf% E7% B7% A8)
• AttributeError: Das Objekt 'AutoSchema' hat kein Attribut 'get_link' und was ist zu tun, wenn die DRF-API-Dokumentgenerierung nicht verwendet werden kann?