django drf_yasg 非restful风格的api怎么在swagger上展示?
发布网友
发布时间：2022-04-25 15:19
共2个回答
热心网友
时间：2022-04-19 01:39
Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。
在web api 使用swagger可以说非常简单，不需要编写任何代码，完全依赖于插件。具体步骤如下：
1.新建一个web api项目
2.使用nuget添加Swashbuckle包
3.完成
没错，就是这么简单！运行项目，转到地址 http://localhost:57700/swagger/ui/index 会看到如下页面，这是默认添加的两个apicontroller：
这个时候接口还没有具体的描述信息等，例如我们给ValuesController.Get添加注释描述，在页面上还是没有显示出来。需要按照如下步骤实现：
1. 在app_start 下 SwaggerConfig 大100行的位置找到 //c.IncludeXmlComments(GetXmlCommentsPath()); 如下注释，改为：c.IncludeXmlComments(GetXmlCommentsPath(thisAssembly.GetName().Name)); （注意去掉注释了）
2. 在SwaggerConfig添加一个方法代码：
1
2
3
4
protected static string GetXmlCommentsPath(string name)
{
return string.Format(@"{0}\bin\{1}.XML", AppDomain.CurrentDomain.BaseDirectory, name);
}
3. 修改项目生成，在bin下对应的xml文件可以看到具体的描述文档，如下：
重新生成项目，就要可以看到完整的接口描述了。例如我们心中一个TestController如下：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
/// <summary>
/// 测试控制器
/// </summary>
public class TestController : ApiController
{
/// <summary>
/// 测试Get方法
/// </summary>
/// <remarks>测试Get方法</remarks>
/// <returns></returns>
[HttpGet]
public string Get()
{
return "Get";
}
/// <summary>
/// 测试Post方法
/// </summary>
/// <param name="name">姓名</param>
/// <param name="age">年龄</param>
/// <remarks>测试Post方法</remarks>
/// <returns></returns>
[HttpPost]
public string Post(string name, int age)
{
return name + age.ToString();
}
}
生成的页面如下，可以看到接口的描述，点击Try it out 即可调用：
三、非依赖代码
上面的方式依赖于Swashbuckle包，它已经包含了Swagger-UI组件。我们的代码需要引入这个包，实际上也可以不需要在项目中引入，单独部署Swagger,包括Swagger-Ui（api展示） 和 Swagger-Editor（在线编辑器），它需要依赖nodejs环境，所以需要先按照nodejs。部署其实也很简单，例如这是我部署的结果：
swagger-editor:
swagger-ui:
编辑后只需要将文件保存为json文件，然后拷贝到指定的目录即可。这个部署也非常简单，具体可以参照：
热心网友
时间：2022-04-19 02:57
前提: 本人开发环境是mac10.14.4，Python3.7.2
django-rest-swagger vs drf-yasg
百度google各种查询帖子，python中生成自动化API文档绝大部分用的都是django-rest-swagger库，然而此库作者表示在2019-06-04已停止更新，而且此库需要的第三方版本库是：
Django 1.8+
Django REST framework 3.5.1+
Python 2.7, 3.5, 3.6
换句话说，django-rest-swagger并不支持Python3.7的环境，所以本人选择了drf-yasg库，它需要的第三方版本库是：
Django Rest Framework: 3.8, 3.9
Django: 1.11, 2.1, 2.2
Python: 2.7, 3.5, 3.6, 3.7
drf-yasg快速上手
安装
pip install -U drf-yasg
1
1
在settings.py声明app,并将debug设置为true
INSTALLED_APPS = [
...
'drf_yasg',
...
]
DEBUG = True
1
2
3
4
5
6
7
1
2
3
4
5
6
7
在根url.py添加scheme_view
from rest_framework import permissions
from drf_yasg.views import get_schema_view
from drf_yasg import openapi
schema_view = get_schema_view(
openapi.Info(
title="API文档",
default_version='v1.0.0',
contact=openapi.Contact(name='联系开发者', email="your email"),
),
permission_classes=(permissions.AllowAny,),
)
urlpatterns = [
...
url('swagger', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),
]
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
踩坑
1. 找不到drf目录下的静态文件
解决方案：测试环境settings.py中的DEBUG设置为true(方便生成api文档), 生产环境设置为False。在python环境中，如果使用drf库生成API文档，需要将DEBUG设置为true，否则找不到静态文件。
