swagger中怎么添加apis属性

Posted

tags:

篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了swagger中怎么添加apis属性相关的知识,希望对你有一定的参考价值。

参考技术A Web API文档工具列表 Swagger ——Swagger框架可以通过代码生成漂亮的在线API,甚至可以提供运行示例。支持Scala、Java、javascript、Ruby、php甚至 Actionscript 3。在线 Demo 。 I/O Docs ——I/O Docs是一个用于RESTful Web APIs的交互式文档系统...

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

使用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,否则找不到静态文件。

以上是关于swagger中怎么添加apis属性的主要内容,如果未能解决你的问题,请参考以下文章

swagger中@Api和@ApiOperation的position属性不能用了,怎么指定接口及方法的顺序

怎么给swagger添加接口注释

swagger 常用注解

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

怎么在springboot项目中使用swagger-spring-boot-starter

Spring Boot 集成 Swagger,再也不写接口文档了!