记录您的api-Django REST框架
记录API
RESTAPI应该花费几乎所有的描述性工作来定义用于表示资源和驱动应用程序状态的媒体类型。
罗伊·菲尔丁RESTAPI必须是超文本驱动的。
REST框架为生成OpenAPI模式提供了内置支持，它可以与允许您构建API文档的工具一起使用。
还有许多优秀的第三方文档包可供使用。
从OpenAPI模式生成文档
有许多可用的包允许您从OpenAPI模式生成HTML文档页。
两者都只需要静态模式文件或动态模式文件的位置。SchemaView端点。
SwaggerUI的最小示例
假设您遵循了模式文档中的示例来路由动态SchemaView，用于使用Swagger UI的最小Django模板可能如下：
<!DOCTYPE html>
<html>
<head>
<title>Swagger</title>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="stylesheet" type="text/css" href="//unpkg.com/swagger-ui-dist@3/swagger-ui.css" />
</head>
<body>
<div id="swagger-ui"></div>
<script src="//unpkg.com/swagger-ui-dist@3/swagger-ui-bundle.js"></script>
<script>
const ui = SwaggerUIBundle({
url: "{% url schema_url %}",
dom_id: '#swagger-ui',
presets: [
SwaggerUIBundle.presets.apis,
SwaggerUIBundle.SwaggerUIStandalonePreset
],
layout: "BaseLayout"
})
</script>
</body>
</html>
将其保存在模板文件夹中swagger-ui.html...然后路由aTemplateView在项目的URL conf中：
from django.views.generic import TemplateView
urlpatterns = [
# ...
# Route TemplateView to serve Swagger UI template.
# * Provide `extra_context` with view name of `SchemaView`.
path('swagger-ui/', TemplateView.as_view(
template_name='swagger-ui.html',
extra_context={'schema_url':'openapi-schema'}
), name='swagger-ui'),
]
见swagger用户界面文档用于高级用途。
关于ReDoc的一个最小的例子。
假设您遵循了模式文档中的示例来路由动态SchemaView，用于使用Swagger UI的最小Django模板可能如下：
<!DOCTYPE html>
<html>
<head>
<title>ReDoc</title>
<!-- needed for adaptive design -->
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1">
<link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
<!-- ReDoc doesn't change outer page styles -->
<style>
body {
margin: 0;
padding: 0;
}
</style>
</head>
<body>
<redoc spec-url='{% url schema_url %}'></redoc>
<script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"> </script>
</body>
</html>
将其保存在模板文件夹中redoc.html...然后路由aTemplateView在项目的URL conf中：
from django.views.generic import TemplateView
urlpatterns = [
# ...
# Route TemplateView to serve the ReDoc template.
# * Provide `extra_context` with view name of `SchemaView`.
path('redoc/', TemplateView.as_view(
template_name='redoc.html',
extra_context={'schema_url':'openapi-schema'}
), name='redoc'),
]
见ReDoc文档用于高级用途。
第三方包
有许多成熟的第三方包用于提供API文档。
DRF-yasg-又一个摇摆发电机
杜鲁-雅斯格是昂首阔步生成工具在不使用Django REST Framework提供的模式生成的情况下实现。
它的目标是实现尽可能多的OpenAPI尽可能地规范嵌套模式、命名模型、响应体、enum/model/min/max验证器、表单参数等，并生成可用的文档，如swagger-codegen.
这也转化为一个非常有用的交互式文档查看器，其形式为swagger-ui:
Screenshot - drf-yasg
Django REST Swagger
马克·吉本斯Django REST Swagger将REST框架与昂首阔步API文档工具。该包生成良好的API文档，并包含用于测试API端点的交互式工具。
Django REST Swagger支持REST框架版本2.3和更高版本。
Mark也是REST框架文档这个包为您的API提供了干净的、简单的自动生成文档，但是不推荐它，并且已经转移到Django REST Swagger。
这个包有完整的文档，很好的支持，并且受到强烈的推荐。
Screenshot - Django REST Swagger
DRF自动文档
Oleksander Mashianovs‘DRF自动文档自动API渲染器。
毫不费力地收集编写到文档中的几乎所有代码。
支持：
- 功能视图文档
- 树状结构
- 文档字符串：
- 标价
- 保留空间和换行符
- 用很好的语法格式化
- 字段：
- 选择渲染
- Help_Text(指定SerializerMethodField输出等)
- 智能只读/所需呈现
- 端点属性：
- 过滤器后端
- 认证类
- 许可类
- 额外的url params(获取params)
[图片上传失败...(image-d37a63-1572571255172)]
养蜂场
还有其他各种在线工具和服务来提供API文档。一个值得注意的服务是养蜂场...使用Apiary，您可以使用一个简单的类似于标记的语法来描述您的API。生成的文档包括API交互、用于测试和原型的模拟服务器以及其他各种工具。
Screenshot - Apiary
自描述API
REST框架提供的可浏览API使您的API完全自我描述成为可能。可以通过访问浏览器中的URL来提供每个API端点的文档。
Screenshot - Self describing API
设置标题
在可浏览API中使用的标题是从视图、类名或函数名生成的。任何尾随View或ViewSet后缀被去掉，字符串是在大写/小写边界或下划线上分隔的空格。
例如，视图UserListView，将被命名为User List当出现在可浏览API中时。
在处理视图集时，每个生成的视图都会附加一个适当的后缀。例如，视图集UserViewSet将生成名为User List和User Instance.
设置描述
可浏览API中的描述是从视图或视图集的docstring生成的。
如果蟒蛇Markdown则安装库。标记语法可以在docstring中使用，并将在可浏览API中转换为HTML。例如：
class AccountListView(views.APIView):
"""
Returns a list of all **active** accounts in the system.
For more details on how accounts are activated please [see here][ref].
[ref]: http://example.com/activating-accounts
"""
注意，在使用viewset时，所有生成的视图都使用基本docstring。若要为每个视图(如列表和检索视图)提供说明，请使用模式作为文档：示例.
这个OPTIONS方法
RESTFrameworkAPI还支持以编程方式访问的描述，使用OPTIONShttp方法视图将响应OPTIONS包含元数据的请求，包括名称、描述以及它接受和响应的各种媒体类型。
使用泛型视图时，任何OPTIONS请求还将使用元数据对任何POST或PUT操作，描述序列化程序上的哪些字段。
可以将响应行为修改为OPTIONS通过重写options查看方法和/或提供自定义元数据类。例如：
def options(self, request, *args, **kwargs):
"""
Don't include the view description in OPTIONS responses.
"""
meta = self.metadata_class()
data = meta.determine_metadata(request, self)
data.pop('description')
return data
看见元数据文档更多细节。
超媒体方法
要完全RESTful，API应该在其发送的响应中将其可用的操作表示为超媒体控件。
在这种方法中，而不是预先记录可用的api端点，而是将描述集中在媒体类型都是用的。对任何给定URL可能采取的可用操作不是严格固定的，而是通过返回文档中存在的链接和表单控件来提供的。
要实现超媒体API，您需要为该API确定合适的媒体类型，并为该媒体类型实现一个自定义呈现器和解析器。这个休息、超媒体和食盐文档的一部分包括指向背景阅读的指针，以及指向各种超媒体格式的链接。
网友评论