django drf_yasg 非restful风格的api怎么在swagger上展示？

Posted 2023-03-01

使用Swagger

　　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文件，然后拷贝到指定的目录即可。这个部署也非常简单，具体可以参照：

　　 参考技术A PS: 个人深感python开发者社区氛围比安卓/ios/java差多了。不过，这也许是个机会～

前提: 本人开发环境是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，否则找不到静态文件。