DRFフレームワークの概要-インタフェースドキュメントの自動生成

インタフェースドキュメントの自動生成
REST frameworkは、インタフェースドキュメントの生成を自動的に支援します.
インタフェースドキュメントは、Webページで表示されます.
自動インタフェースドキュメントは、APIViewおよびそのサブクラスから継承されたビューを生成することができる.
1.インストール依存
REST framewrok生成インタフェースドキュメントにはcoreapiライブラリのサポートが必要です.

pip install coreapi

2.インタフェースドキュメントへのアクセスパスの設定
総ルーティングにインタフェースドキュメントパスを追加します.
ドキュメントのルーティングに対応するビューはrest_framework.documentation.include_docs_urlsに構成され、
パラメータtitleは、インタフェースドキュメントのWebサイトのタイトルです.

from rest_framework.documentation import include_docs_urls

urlpatterns = [
    ...
    url(r'^docs/', include_docs_urls(title='My API title'))
]

3.ドキュメントの説明の定義場所
1)単一メソッドのビューで、クラスビューのドキュメント文字列を直接使用できます.

class BookListView(generics.ListAPIView):
    """
            .
    """

2)クラスビューのドキュメント文字列で、メソッド定義を区切る複数のメソッドを含むビュー.

class BookListCreateView(generics.ListCreateAPIView):
    """
    get:
            .

    post:
        .
    """

3)ビューセットViewについては、クラスビューのドキュメント文字列で定義を閉じますが、アクション名で区別する必要があります.

class BookInfoViewSet(mixins.ListModelMixin, mixins.RetrieveModelMixin, GenericViewSet):
    """
    list:
            

    retrieve:
            

    latest:
             

    read:
            
    """

4.インタフェースドキュメントのWebページへのアクセス
ブラウザは127.0.0.1:8000/docs/にアクセスし、自動的に生成されたインタフェースドキュメントを表示します.
2点の説明:
1)ビューセットViewSetのretrieve名は,インタフェース文書サイトでreadと呼ぶ.
2)パラメータのDescriptionは、モデルクラスまたはシーケンサクラスのフィールドにhelp_textオプション定義:

class BookInfo(models.Model):
    ...
    bread = models.IntegerField(default=0, verbose_name='   ', help_text='   ')
    ...

または

class BookReadSerializer(serializers.ModelSerializer):
    class Meta:
        model = BookInfo
        fields = ('bread', )
        extra_kwargs = {
            'bread': {
                'required': True,
                'help_text': '   '
            }
        }