drf-yasg 用法

用法

0.安装

首选的安装方法直接来自pypi：

pip install drf-yasg

此外，如果要使用内置验证机制（请参阅4.验证），则需要安装一些额外要求：

pip install drf-yasg[validation]

1.快速入门

在settings.py：

INSTALLED_APPS = [
   ...
   'drf_yasg',
   ...
]

在urls.py：

...
from drf_yasg.views import get_schema_view
from drf_yasg import openapi

...

schema_view = get_schema_view(
   openapi.Info(
      title="Snippets API",
      default_version='v1',
      description="Test description",
      terms_of_service="https://www.google.com/policies/terms/",
      contact=openapi.Contact(email="[email protected]"),
      license=openapi.License(name="BSD License"),
   ),
   validators=['flex', 'ssv'],
   public=True,
   permission_classes=(permissions.AllowAny,),
)

urlpatterns = [
   url(r'^swagger(?P\.json|\.yaml)$', schema_view.without_ui(cache_timeout=None), name='schema-json'),
   url(r'^swagger/$', schema_view.with_ui('swagger', cache_timeout=None), name='schema-swagger-ui'),
   url(r'^redoc/$', schema_view.with_ui('redoc', cache_timeout=None), name='schema-redoc'),
   ...
]

这暴露了4个缓存，验证和公开可用的端点：

• 您的API规范的JSON视图 /swagger.json
• 您的API规范的YAML视图 /swagger.yaml
• 一个swagger-ui的API规范视图 /swagger/
• 您的API规范的ReDoc视图 /redoc/

2.配置

一个。get_schema_view参数

• info - Swagger API Info对象; 如果省略，则默认为DEFAULT_INFO
• url - API基本网址; 如果留空，则将从提供视图的位置推断出
• patterns - 传递给SchemaGenerator
• urlconf - 传递给SchemaGenerator
• public - 如果为False，则仅包括当前用户有权访问的端点
• validators - 要在生成的模式上应用的验证器名称列表; 允许的值是flex，ssv
• generator_class - 要使用的模式生成器类; 应该是的子类OpenAPISchemaGenerator
• authentication_classes - 架构视图本身的身份验证类
• permission_classes - 架构视图本身的权限类

湾 SchemaView选项

• SchemaView.with_ui(renderer, cache_timeout, cache_kwargs) - 使用指定的UI渲染器获取视图实例; 之一swagger，redoc
• SchemaView.without_ui(cache_timeout, cache_kwargs) - 获取没有UI渲染器的视图实例; 一样as_cached_view没有kwargs
• SchemaView.as_cached_view(cache_timeout, cache_kwargs, **initkwargs)- as_view与之相同，但具有可选的缓存
• 当然，你可以as_view照常打电话

所有前3个方法都有两个可选参数，cache_timeout并且cache_kwargs; 如果存在，这些将传递给Django的cached_page装饰器，以便在结果视图上启用缓存。请参阅3.缓存。

C。SWAGGER_SETTINGS和REDOC_SETTINGS

此外，您还可以在settings.py文件中包含更多设置。有关详细信息，请参阅https://drf-yasg.readthedocs.io/en/stable/settings.html。

3.缓存

由于架构在django进程的生命周期中通常不会发生更改，因此可以使用开箱即用的支持来缓存内存中的架构视图，并使用一些合理的默认值：

• 缓存由cache_page 装饰器启用，使用默认的Django缓存后端，可以使用cache_kwargs参数进行更改
• 阻止响应的HTTP缓存，以避免因显示过时模式而导致的混乱情况
• 缓存的模式在Cookie和AuthorizationHTTP标头上有所不同，以根据每个用户的身份验证凭据启用可见端点的过滤; 请注意，这意味着访问该架构的每个用户都将在内存中缓存一个单独的架构。

4.验证

鉴于手动定制生成的模式的众多方法，验证结果以确保它仍然符合OpenAPI 2.0是有意义的。为此，使用python swagger库在生成点提供验证，并且可以通过传递来激活; 如果生成的模式无效，则处理编解码器会引发a 。validators=[‘flex’, ‘ssv’]get_schema_viewSwaggerValidationError

警告：此内部验证可能会降低服务器速度。缓存可以减轻验证的速度影响。

提供的验证将捕获语法错误，但更严重的违反规范的行为可能会因此而失误。为确保与代码生成工具的兼容性，建议还使用以下一种或多种方法：

swagger-ui验证徽章

在线

如果您的架构可公开访问，swagger-ui将根据官方swagger在线验证器自动验证它，并在右下角验证徽章中显示结果。

离线

如果无法从Internet访问您的架构，则可以运行swagger-validator的本地副本 并相应地设置VALIDATOR_URL：

SWAGGER_SETTINGS = {
    ...
    'VALIDATOR_URL': 'http://localhost:8189',
    ...
}

$ docker run --name swagger-validator -d -p 8189:8080 --add-host test.local:10.0.75.1 swaggerapi/swagger-validator
84dabd52ba967c32ae6b660934fa6a429ca6bc9e594d56e822a858b57039c8a2
$ curl http://localhost:8189/debug?url=http://test.local:8002/swagger/?format=openapi
{}

使用swagger-cli

https://www.npmjs.com/package/swagger-cli

$ npm install -g swagger-cli
[...]
$ swagger-cli validate http://test.local:8002/swagger.yaml
http://test.local:8002/swagger.yaml is valid

在editor.swagger.io上手动

将生成的规范导入https://editor.swagger.io/将自动触发验证。此方法是目前在您的规范上获得语法和语义验证的唯一方法。其他验证器仅提供JSON模式级验证，但遗漏了重复操作名称，不正确的内容类型等内容

5.代码生成

您可以使用此库输出的规范以及 swagger-codegen以您选择的语言生成客户端代码：

$ docker run --rm -v ${PWD}:/local swaggerapi/swagger-codegen-cli generate -i /local/tests/reference.yaml -l javascript -o /local/.codegen/js

有关更多详细信息，请参阅上面链接的github页面。

6.示例项目

有关其他用法示例，您可以查看testproj目录中的测试项目：

$ git clone https://github.com/axnsan12/drf-yasg.git
$ cd drf-yasg
$ virtualenv venv
$ source venv/bin/activate
(venv) $ cd testproj
(venv) $ pip install -r requirements.txt
(venv) $ python manage.py migrate
(venv) $ python manage.py shell -c "import createsuperuser"
(venv) $ python manage.py runserver
(venv) $ firefox localhost:8000/swagger/

背景

OpenAPI 2.0/ Swagger是一种格式，用于将有关Web API的信息编码为易于解析的模式，然后可用于呈现文档，生成代码等。

有关swagger.io和OpenAPI 2.0规范页面的更多详细信息。

从这里开始，术语“OpenAPI”和“Swagger”可互换使用。

Django Rest Framework中的

自Django Rest 3.7以来，现在内置了对自动OpenAPI 2.0模式生成的支持。然而，这一代基于coreapi 标准，目前在功能和工具支持方面远远低于OpenAPI。特别是，提供的OpenAPI编解码器/兼容性层有一些主要问题：

• 不支持记录响应模式和状态代码
• 嵌套模式无法正常工作
• 不处理更复杂的领域，例如FileField，ChoiceField，...

简而言之，这使得生成的模式不能用于代码生成，并且最好是文档中的平庸。

其他图书馆

目前有两个像样的Swagger模式生成器，我可以找到django-rest-framework：

• Django的休息，招摇
• DRF-的OpenAPI

在这两者中，django-rest-swagger只是一个包含DRF 3.7模式生成的包装器，增加了UI，因此存在同样的问题。drf-openapi有一点涉及并为响应模式实现一些自定义处理，但最终仍然在代码生成方面不足，因为响应很明显缺乏对命名模式的支持。

这两个项目目前也没有任何数据。

第三方集成

djangorestframework -驼峰

与djangorestframework-camel-case的集成是开箱即用的 - 如果您已经djangorestframework-camel-case安装并APIView使用了 CamelCaseJSONParser或者CamelCaseJSONRenderer，默认情况下所有属性名称都将转换为camelCase。

djangorestframework递归

与djangorestframework-recursive集成是开箱即用的 - 如果你已经djangorestframework-recursive安装了。