Django（74）drf-spectacular自動生成接口文檔

介紹

drf-spectacular是為Django REST Framework生成合理靈活的OpenAPI 3.0模式。它可以自動幫我們提取接口中的信息，從而形成接口文檔，而且內容十分詳細，再也不用為寫接口文檔而心煩了

這個庫主要實現了3個目標

• 從DRF中提取更多的schema信息
• 提供靈活性，使schema在現實世界中可用(不僅僅是示例)
• 生成一個與最流行的客戶端生成器配合良好的schema
   

環境准備

• Python >= 3.6
• Django (2.2, 3.1, 3.2)
• Django REST Framework (3.10, 3.11, 3.12)
   

安裝

使用pip命令安裝

pip install drf-spectacular

然后在settings.py的INSTALLED_APPS安裝drf-spectacular

INSTALLED_APPS = [
    # ALL YOUR APPS
    'drf_spectacular',
]

最后向DRF注冊我們壯觀的AutoSchema

REST_FRAMEWORK = {
    # YOUR SETTINGS
    'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema',
}

drf-spectacular有健全的默認設置，非常好用開箱即用，不需要指定任何設置，但我們建議至少指定一些元數據

SPECTACULAR_SETTINGS = {
    'TITLE': 'API接口文檔',
    'DESCRIPTION': '項目詳情介紹',
    'VERSION': '1.0.0',
    # OTHER SETTINGS
}

 

使用方式

我們只需要在urls.py中添加接口地址即可

from drf_spectacular.views import SpectacularAPIView, SpectacularRedocView, SpectacularSwaggerView
urlpatterns = [
    # YOUR PATTERNS
    path('api/schema/', SpectacularAPIView.as_view(), name='schema'),
    # Optional UI:
    path('api/schema/swagger-ui/', SpectacularSwaggerView.as_view(url_name='schema'), name='swagger-ui'),  # swagger接口文檔
    path('api/schema/redoc/', SpectacularRedocView.as_view(url_name='schema'), name='redoc'),  # redoc接口文檔
]

然后我們啟動項目，訪問http://127.0.0.1:8000/api/schema/swagger-ui/，就會出現接口文檔

我們可以看到圖上有我們之前在settings.py中配置的TITLE和DESCRIPTION和VERSION，如果想自定義更多的設置，請看文檔
 

自定義接口內容信息

上面我們可以訪問swagger接口文檔，但是我們點開接口會發現沒有任何內容信息

所以我們還需要在view視圖中，使用裝飾器@extend_schema來制定接口文檔中的接口信息

我們先來看下裝飾器extend_schema的源碼

def extend_schema(
        operation_id: Optional[str] = None,
        parameters: Optional[List[Union[OpenApiParameter, _SerializerType]]] = None,
        request: Any = empty,
        responses: Any = empty,
        auth: Optional[List[str]] = None,
        description: Optional[str] = None,
        summary: Optional[str] = None,
        deprecated: Optional[bool] = None,
        tags: Optional[List[str]] = None,
        exclude: bool = False,
        operation: Optional[Dict] = None,
        methods: Optional[List[str]] = None,
        versions: Optional[List[str]] = None,
        examples: Optional[List[OpenApiExample]] = None,
        extensions: Optional[Dict[str, Any]] = None,
) -> Callable[[F], F]:
    """
    Decorator mainly for the "view" method kind. Partially or completely overrides
    what would be otherwise generated by drf-spectacular.

    :param operation_id: replaces the auto-generated operation_id. make sure there
        are no naming collisions.
    :param parameters: list of additional or replacement parameters added to the
        auto-discovered fields.
    :param responses: replaces the discovered Serializer. Takes a variety of
        inputs that can be used individually or combined

        - ``Serializer`` class
        - ``Serializer`` instance (e.g. ``Serializer(many=True)`` for listings)
        - basic types or instances of ``OpenApiTypes``
        - :class:`.OpenApiResponse` for bundling any of the other choices together with
          either a dedicated response description and/or examples.
        - :class:`.PolymorphicProxySerializer` for signaling that
          the operation may yield data from different serializers depending
          on the circumstances.
        - ``dict`` with status codes as keys and one of the above as values.
          Additionally in this case, it is also possible to provide a raw schema dict
          as value.
        - ``dict`` with tuples (status_code, media_type) as keys and one of the above
          as values. Additionally in this case, it is also possible to provide a raw
          schema dict as value.
    :param request: replaces the discovered ``Serializer``. Takes a variety of inputs

        - ``Serializer`` class/instance
        - basic types or instances of ``OpenApiTypes``
        - :class:`.PolymorphicProxySerializer` for signaling that the operation
          accepts a set of different types of objects.
        - ``dict`` with media_type as keys and one of the above as values. Additionally in
          this case, it is also possible to provide a raw schema dict as value.
    :param auth: replace discovered auth with explicit list of auth methods
    :param description: replaces discovered doc strings
    :param summary: an optional short summary of the description
    :param deprecated: mark operation as deprecated
    :param tags: override default list of tags
    :param exclude: set True to exclude operation from schema
    :param operation: manually override what auto-discovery would generate. you must
        provide a OpenAPI3-compliant dictionary that gets directly translated to YAML.
    :param methods: scope extend_schema to specific methods. matches all by default.
    :param versions: scope extend_schema to specific API version. matches all by default.
    :param examples: attach request/response examples to the operation
    :param extensions: specification extensions, e.g. ``x-badges``, ``x-code-samples``, etc.
    :return:
    """
    if methods is not None:
        methods = [method.upper() for method in methods]

    def decorator(f):
        BaseSchema = (
            # explicit manually set schema or previous view annotation
            getattr(f, 'schema', None)
            # previously set schema with @extend_schema on views methods
            or getattr(f, 'kwargs', {}).get('schema', None)
            # previously set schema with @extend_schema on @api_view
            or getattr(getattr(f, 'cls', None), 'kwargs', {}).get('schema', None)
            # the default
            or api_settings.DEFAULT_SCHEMA_CLASS
        )

        if not inspect.isclass(BaseSchema):
            BaseSchema = BaseSchema.__class__

        def is_in_scope(ext_schema):
            version, _ = ext_schema.view.determine_version(
                ext_schema.view.request,
                **ext_schema.view.kwargs
            )
            version_scope = versions is None or version in versions
            method_scope = methods is None or ext_schema.method in methods
            return method_scope and version_scope

        class ExtendedSchema(BaseSchema):
            def get_operation(self, path, path_regex, path_prefix, method, registry):
                self.method = method.upper()

                if exclude and is_in_scope(self):
                    return None
                if operation is not None and is_in_scope(self):
                    return operation
                return super().get_operation(path, path_regex, path_prefix, method, registry)

            def get_operation_id(self):
                if operation_id and is_in_scope(self):
                    return operation_id
                return super().get_operation_id()

            def get_override_parameters(self):
                if parameters and is_in_scope(self):
                    return super().get_override_parameters() + parameters
                return super().get_override_parameters()

            def get_auth(self):
                if auth and is_in_scope(self):
                    return auth
                return super().get_auth()

            def get_examples(self):
                if examples and is_in_scope(self):
                    return super().get_examples() + examples
                return super().get_examples()

            def get_request_serializer(self):
                if request is not empty and is_in_scope(self):
                    return request
                return super().get_request_serializer()

            def get_response_serializers(self):
                if responses is not empty and is_in_scope(self):
                    return responses
                return super().get_response_serializers()

            def get_description(self):
                if description and is_in_scope(self):
                    return description
                return super().get_description()

            def get_summary(self):
                if summary and is_in_scope(self):
                    return str(summary)
                return super().get_summary()

            def is_deprecated(self):
                if deprecated and is_in_scope(self):
                    return deprecated
                return super().is_deprecated()

            def get_tags(self):
                if tags is not None and is_in_scope(self):
                    return tags
                return super().get_tags()

            def get_extensions(self):
                if extensions and is_in_scope(self):
                    return extensions
                return super().get_extensions()

        if inspect.isclass(f):
            # either direct decoration of views, or unpacked @api_view from OpenApiViewExtension
            if operation_id is not None or operation is not None:
                error(
                    f'using @extend_schema on viewset class {f.__name__} with parameters '
                    f'operation_id or operation will most likely result in a broken schema.'
                )
            # reorder schema class MRO so that view method annotation takes precedence
            # over view class annotation. only relevant if there is a method annotation
            for view_method_name in get_view_method_names(view=f, schema=BaseSchema):
                if 'schema' not in getattr(getattr(f, view_method_name), 'kwargs', {}):
                    continue
                view_method = isolate_view_method(f, view_method_name)
                view_method.kwargs['schema'] = type(
                    'ExtendedMetaSchema', (view_method.kwargs['schema'], ExtendedSchema), {}
                )
            # persist schema on class to provide annotation to derived view methods.
            # the second purpose is to serve as base for view multi-annotation
            f.schema = ExtendedSchema()
            return f
        elif callable(f) and hasattr(f, 'cls'):
            # 'cls' attr signals that as_view() was called, which only applies to @api_view.
            # keep a "unused" schema reference at root level for multi annotation convenience.
            setattr(f.cls, 'kwargs', {'schema': ExtendedSchema})
            # set schema on method kwargs context to emulate regular view behaviour.
            for method in f.cls.http_method_names:
                setattr(getattr(f.cls, method), 'kwargs', {'schema': ExtendedSchema})
            return f
        elif callable(f):
            # custom actions have kwargs in their context, others don't. create it so our create_view
            # implementation can overwrite the default schema
            if not hasattr(f, 'kwargs'):
                f.kwargs = {}
            # this simulates what @action is actually doing. somewhere along the line in this process
            # the schema is picked up from kwargs and used. it's involved my dear friends.
            # use class instead of instance due to descriptor weakref reverse collisions
            f.kwargs['schema'] = ExtendedSchema
            return f
        else:
            return f

    return decorator

這個裝飾器主要用於view，通過drf-spectacular部分或完全的覆蓋去產生些東西

先來看下幾個初始化參數

• operation_id：一個唯一標識ID，基本用不到
• parameters：添加到列表中的附加或替換參數去自動發現字段。
• responses：替換Serializer。需要各種各樣的可單獨使用或組合使用的輸入(有以下7種)
  • Serializer類
  • 序列化實例，比如：Serializer(many=True)
  • OpenApiTypes的基本類型或者實例
  • OpenApiResponse類
  • PolymorphicProxySerializer類
  • 1個字典，以狀態碼作為鍵， 以上其中一項作為值(是最常用的，格式{200, None})
  • 1個字典，以狀態碼作為鍵，以media_type作為值
• request：替換序列化，接受各種輸入
  • Serializer 類或者實例
  • OpenApiTypes基本類型或者實例
  • PolymorphicProxySerializer類
  • 1個字典，以media_type作為鍵，以上其中一項作為值
• auth：用auth方法的顯式列表替換發現的auth
• description：替換發現的文檔字符串
• summary：一個可選的短的總結描述
• deprecated：將操作標記為已棄用
• tags：覆蓋默認標記列表
• exclude：設置為True以從schema中排除操作
• operation：手動覆蓋自動發現將生成的內容。你必須提供一個兼容OpenAPI3的字典，該字典可以直接翻譯成YAML。
• methods：檢查extend_schema中特殊的方法，默認匹配所有
• versions：檢查extend_schema中特殊的API版本，默認匹配所有
• example：將請求/響應示例附加到操作中
• extensions：規范擴展

最后我們在登錄視圖的post方法中添加@extend_schema裝飾器，傳入上面你所需要的字段，就可以了

@extend_schema(
        summary="Login",
        request=UserModelSerializer,
        responses={200: UserModelSerializer},
        description="登錄接口",
        versions=["v1"]
    )

最后我們就能看到完整的接口文檔了