Comment générer automatiquement un document API avec le framework Django REST et POST à partir de l'écran de document

Dans cet article, nous vous expliquerons comment générer automatiquement le document API (explication de l'utilisation, etc.) lors de la création d'une API avec le framework Django REST.

Étape 0: DRF (framework Django REST)

Cette fois, j'utilise ** version: 3.10.3 **. La dernière version (septembre 2020) est la ** version: 3.11.1 **.

Étape 1: installer des packages supplémentaires

Installez les packages requis pour la documentation API automatique.

pip install coreapi
pip install Pygments
pip install Markdown

Étape 2: définir une page de documentation dans urls.py

Pour urls.py dans le dossier de l'application qui est la base de l'application Django

from rest_framework.documentation import include_docs_urls

Pour activer l'utilisation de ʻinclude_docs_urls () `.

Ensuite, définissez path (" docs / "...) dans urls.py de l'application comme suit.

...

from rest_framework.documentation import include_docs_urls

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

Maintenant, si vous accédez à / docs (par exemple, http: // localhost: 8000 / docs /), vous verrez la page de documentation de l'API comme indiqué ci-dessous.

** * Contre-mesures d'erreur ** Lors de l'accès à la page de documentation, l'objet ʻautoschema'object n'a pas d'attribut'get_link 'django` Si l'erreur s'affiche,

Dans le settingts.py du dossier de l'application, comme suit 'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.coreapi.AutoSchema' Sera ajouté.

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

Cela se produit si vous utilisez DRF version 3.10 ou supérieure.

(Référence) Django REST Framework 3.10 https://www.django-rest-framework.org/community/3.10-announcement/

Étape 3: Comment lire l'écran de documentation

En bas à gauche de l'écran, il y a des menus appelés Authentification et Code source.

[3.1] Vous pouvez vous connecter en déployant l'authentification. Si vous vous connectez ici, vous pouvez accéder à l'API à partir de cet écran de documentation lorsque vous êtes connecté. (Comment accéder à l'API sera expliqué dans la section suivante).

[3.2] Le code source utilise coreapi sur le côté droit de l'écran

• shell
• Javascript
• Python

Vous pouvez afficher le code d'implémentation pour chaque API

** * Contre-mesures d'erreur ** Si vous accédez à l'écran normal de l'API au lieu de l'écran de documentation pour une raison quelconque, si vous accédez à docs / tout en étant connecté une fois depuis l'écran d'administration de Django, l'écran de documentation s'affiche (cause inconnue).

Étape 3: Préparez la description de l'API

Pour le moment, il n'y a aucune explication de l'opération pour chaque API. (Puisque {id} est pris dans l'URL uniquement pour la lecture, "id" est automatiquement décrit comme un paramètre obligatoire)

Ajoutez une description de chaque API ici.

Si vous écrivez un commentaire pour la "classe ViewSet" qui hérite de viewssets.ViewSet etc. dans views.py de l'application correspondante, il sera reflété dans la documentation en tant qu'explication de l'API.

Par exemple, viewssets.ViewSet Puisque l'API est divisée en chaque classe de liste, créez, récupérez, mettez à jour, partial_update, détruisez, Décrivez la description de l'API pour chacune de ces classes.

La mise en œuvre est la suivante.

class DatasetViewset(viewsets.ViewSet):
    """
    list:
Obtenez des informations sur tous les ensembles de données.

    create:
Créez de nouvelles méta-informations sur l'ensemble de données.

    retrieve:
Obtenez les informations de l'ensemble de données individuel spécifié par pk.
　　　
    """

    def list(self, request):
・ ・ ・

Ensuite, l'explication décrite ci-dessous sera ajoutée à la documentation de l'API.

De plus, lors de la description de l'explication de l'API, le type de contenu à décrire sera expliqué à la fin de cet article.

Étape 4: pouvoir accéder à l'API

Vous pouvez accéder à l'API à partir de cet écran de documentation. Si vous cliquez sur le bouton vert "Interagir" au centre de l'écran ci-dessus, l'écran pour accéder à l'API apparaîtra.

C'est bien pour les systèmes GET, mais les systèmes create (POST) et PUT sont actuellement incomplets.

De plus, dans la figure précédente, les paramètres requis pour créer et placer ne sont pas décrits, ce qui est insuffisant pour expliquer l'API.

Même si je clique sur le bouton "Interagir" de créer, l'écran ci-dessous s'affiche et je ne peux pas écrire les valeurs des paramètres à POSTER.

Il existe différentes manières de préparer l'explication de ce type POST et de l'API de type PUT afin que vous puissiez accéder à l'API POST.

Le schéma du framework Django REST en est l'explication. https://www.django-rest-framework.org/api-guide/schemas/

Un moyen simple est de def get_serializer(self): Le code de est décrit dans la classe ViewSet, et pour chaque méthode, C'est une stratégie pour décrire le sérialiseur utilisé dans cette méthode et le détourner.

class DatasetViewset(viewsets.ViewSet):
    """
    list:
Obtenez des informations sur tous les ensembles de données.

    create:
Créez de nouvelles méta-informations sur l'ensemble de données.

    retrieve:
Obtenez les informations de l'ensemble de données individuel spécifié par pk.
    """

    def get_serializer(self):
        """Pour la documentation API"""
        if self.action is "create":
            return DatasetCreateInputSerializer()
        elif self.action is "update":
            return DatasetUpdateMetadataInputSerializer()

    def list(self, request):
・ ・ ・

Ensuite, l'écran de documentation change comme suit.

La figure ci-dessus est un peu difficile à voir, mais la création et la mise à jour ont les paramètres requis pour chaque API.

La dernière chose à craindre est qu'il n'y a pas de description dans la description de chaque paramètre.

Pour décrire la description afin d'expliquer correctement les arguments utilisés dans cette API, accédez à models.py

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

Décrivez l'explication dans l'argument "help_text" comme dans.

Si vous avez créé une classe indépendante du modèle dans les sérialiseurs.Serializer dans les sérialiseurs, décrivez-la dans l'argument "help_text" de ce champ.

Ensuite, l'écran de documentation sera comme suit, et la description de chaque paramètre sera entrée dans la Description telle que "Nom du jeu de données".

Et s'il est dans cet état (def get_serializer () est décrit dans la classe ViewSet et le sérialiseur utilisé dans cette méthode est spécifié pour chaque méthode),

Si vous cliquez sur le bouton vert "Interagir" au centre de l'écran, l'écran pour frapper l'API apparaîtra avec les arguments affichés.

Vous pouvez maintenant POSTER cette API en entrant la valeur de chaque paramètre lorsque vous appuyez sur l'API sur le côté gauche et en cliquant sur «Envoyer la demande» en bas à droite.

Étape 5: Ce que vous souhaitez voir décrit dans la description de l'API

Enfin, je vais vous expliquer ce que je veux que vous décriviez dans l'explication de l'API.

** Ce qui est important, c'est un désir compatissant de créer une documentation API facile à comprendre et à comprendre du point de vue de l'utilisateur utilisant l'API. ** **

Le contenu que vous souhaitez décrire diffère considérablement selon que l'API est utilisée uniquement à l'intérieur du système et uniquement par l'équipe de développement, ou si l'API est exposée à l'extérieur.

en tous cas,

• Résumé de l'opération API (résultats produits) --Détails du fonctionnement de l'API (s'il existe un lien vers le diagramme UML, décrivez le lien)
• Code d'état de la réponse HTTP sous la forme normale d'API et contenu renvoyé --Arguments (nom, description, obligatoire, type)
• Code d'état de réponse HTTP anormal et contenu renvoyé

Je le veux.

Pour les autres contenus qui devraient être décrits dans l'API

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

● Guide de conception d'API de Google https://cloud.google.com/apis/design

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

● Livre de style API http://apistylebook.com/

Je pense que c'est une bonne idée de faire correspondre ce que vous écrivez avec votre propre équipe, en vous référant à ce qui précède.

Voici comment générer automatiquement des documents API avec le framework Django REST & POST à partir de l'écran de document.

Remarques

** 【Transmission d'informations】 ** En plus des impressions des livres que je lis, je publie sur Twitter des articles et des sites que je trouve intéressants en informatique / IA et business / management. Si vous souhaitez collecter des informations sur ces champs, veuillez nous suivre ♪ (Il y a beaucoup d'informations à l'étranger)

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

** [Autre] ** L '«équipe de développement du département de technologie de l'IA» que je dirige recherche des membres. Si tu es intéressé Cette page Merci ♪

** [Sokumen-kun] ** Si vous souhaitez postuler soudainement, nous aurons un entretien informel avec "Sokumen-kun". Veuillez également l'utiliser ♪ https://sokumenkun.com/2020/08/17/yutaro-ogawa/

[Clause de non-responsabilité] Le contenu de cet article lui-même est l'opinion / la transmission de l'auteur, et non l'opinion officielle de la société à laquelle l'auteur appartient.

Autres références dans cet article

• Built-in API documentation
• [Django Rest Framework pour la création d'un site de concours de données](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: l'objet 'AutoSchema' n'a pas d'attribut'get_link 'et que faire si la génération de document de l'API DRF ne peut pas être utilisée