DjangoRestFrameworkのコードからSwaggerドキュメントを生成しAPI設計を共有

9763 ワード
swagger Django django-rest-framework Django テキストリンク

弊社開発環境

弊社のエンジニアチームでは以下の開発環境が最近の主流です。

サーバーサイド： Django + DjangoRestFramework(API)
WEBクライアント： Vue.js
アプリクライアント： Flutter( + Swift)( + Kotlin)

サーバーサイドとクライアントサイドで違う人が開発する場合は多く、
そのようなときにAPI設計を共有するのって難しいですよね。
そのときにSwaggerを使ったAPI設計の共有ドキュメントを生成しています。

イメージ図（Swaggerを書くと１つのAPIでこれだけの情報が取り出せます）

どうやって書いているのか

コードからドキュメントを自動生成しています。

class AbcApiView(ApiView):
    @swagger_auto_schema(
        request_body=AbcRequestSerializer,
        responses={200: openapi.Response('OK', AbcResponseSerializer)})
    def post(self, request, *args, **kwargs):
        """
        期間限定キャンペーンで無料になっている商品を一覧表示
        """
        pass

DRFでSerializerを作っている人は、request_bodyとresponsesにSerializerの型を渡すだけ😍
これだけでドキュメントを生成してくれます。
ドキュメントを追加するのに3行のコードと1行の説明文(docstring)だけで済みます!!

ついでにSerializerも貼っておきます。

class AbcRequestSerializer(serializers.Serializer):
    page = serializers.IntegerField(default=1)
    genre = serializers.CharField(default='', allow_blank=True, allow_null=True)

class AbcApiResponseSerializer(serializers.Serializer):
    items = serializers.ListField(child=ZyxSerializer(), default=[])
    page = serializers.IntegerField()
    has_next = serializers.BooleanField()
    has_prev = serializers.BooleanField()
    max_page = serializers.IntegerField()

シリアライザーにフィールドを追加したいとき、ドキュメントをメンテしなくて済むのでラクチンですね。

yamlでも書ける

yamlで書いてみると以下のようになります。

paths:
  /api/campaign/v1/:
    post:
      summary: 期間限定キャンペーンで無料になっている商品を一覧表示
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                page:
                  type: integer
                genre:
                  type: string
                  default: ""
              example:   # Sample object
                page: 2
                name: "MANGA"
      responses:
        '200':
          description: OK

長い!!!! ( responseを書くのを諦めた

設計段階の場合はこれでいいのですが、たくさんのエンドポイントを作っているとファイルが１０００行くらいすぐに増えます。またメンテもしなくなるので、古いドキュメントが完成です。

docstringの部分には、もうちょっと複雑なことも書ける

docstringの部分には、htmlやコードも書けます。

class AbcApiView(ApiView):
    def post(self, request, *args, **kwargs):
    """
    まとめ買いのリスト表示を行います。

    :param tcode: 基準となるコードを入力します。

    :return 200 ok_response

    ```
    [{
        title_code: 'tcode1', // タイトルコードが一意でない場合がある。シリーズもの。
        serial_number: 1 // tcodeとserial_numberの２つで一意
        price: 0, // 購入するための金額
        is_purchased: false,　// 購入済みの場合はグレーアウト
        is_selected: false, // 購入対象をユーザーが選択
        regular_price: 100, // 通常価格
        campaign_text: 'campaign' // 無料・半額キャンペーン情報
        thumbnail_image_path: '/favicon/favicon256.png' // サムネイル
    },]
    ```
    priceとregular_priceは違うものになります。<br>
    regular_priceは通常価格。<br>
    500円のものを途中まで購入している場合は、priceは300
    """

↓

インストール & 設定

https://github.com/axnsan12/drf-yasg
に従ってインストールすればすぐに使えました😁

一点だけ変更したところを記載します。

schema_view = get_schema_view(
    ....
    permission_classes=(permissions.AllowAny,) if settings.DEBUG else (permissions.IsAdminUser,),
)

permission_classesは閲覧権限です。
ローカルではログインしていなくても閲覧できますが、ローカル以外では管理者権限でないと閲覧できないようにしました。

以上です。
明日は弊社CTOの@ytyng先生のDjangoAdmin教室です！