drf-yasg 用法

最新推荐文章于 2024-08-12 08:59:34 发布

myprogram513

最新推荐文章于 2024-08-12 08:59:34 发布

阅读量1.1w

点赞数

本文链接：https://blog.csdn.net/lmz_lmz/article/details/80986106

版权

用法

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="contact@snippets.local"),
      license=openapi.License(name="BSD License"),
   ),
   validators=['flex', 'ssv'],
   public=True,
   permission_classes=(permissions.AllowAny,),
)

urlpatterns = [
   url(r'^swagger(?P<format>\.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/
 
   