Django Swagger 和 JSON API 渲染问题答案

【问题标题】：Django Swagger and JSON API render issuesDjango Swagger 和 JSON API 渲染问题
【发布时间】：2017-09-11 14:08:48
【问题描述】：

使用 django-rest-framework-json-api 我能够创建 API 端点，其工作方式如文档中所述。尝试使用django-rest-swagger 提供 API 文档并不容易。

1：Swagger 使用 JSON API 不支持的media_type = 'application/json'。为了解决这个问题，我创建了第二个渲染类 (renderer_classes)，它对 JSON API JSONRenderer 进行子类化并强制使用媒体类型。

现在端点支持application/json 和application/vnd.api+json 并且swagger 很乐意以JSON API 文档结构呈现。注意生成的 curl 请求没有标准的 JSON API 标头。

2：Swagger 与解析器有同样的问题。虽然第 1 期的工作确实有效，但还有一个次要挑战。 Swagger 呈现一个字段名称的平面字典，它不是 JSON API，最终由 DRF 请求。

是否可以大摇大摆地在 JSON API 中解析？目前 Swagger 不适用于 PUT 或 POST。

djangorestframework-jsonapi==2.2.0
djangorestframework==3.5.4
Django==1.11.2
coreapi==2.3.1
python 3.6

【问题讨论】：

这听起来像是两个项目之一的错误。 django-rest-swagger 会查看模型模式并忽略视图的细节，或者django-rest-framework-json-api 没有将其视图模式正确地呈现给文档生成器。或者django-rest-framework 甚至没有办法让视图将其模式呈现给文档生成器。无论哪种方式，我都不怀疑有一种方法可以在不修改库的情况下解决它。
@ZeusttheUnoobian 我觉得问题出在django-rest-swagger 内，但同意你的 cmets。

【解决方案1】：

在这里回答我自己的问题，以便其他人可以从所学知识中获得价值。我们从未找到解决此问题的方法，也没有时间为该项目做出贡献。总的来说，这个项目似乎也很艰难，可能是因为像我们这样的人没有做出贡献……

现在出现了一个替代项目drf-yasg，该项目在最初发布时并不存在。 drf-yasg 相对容易部署并解决了我们所有的问题，所以我们现在已经迁移到这个项目。

因此，如果您正在寻找在 DRF 中创建的 JSON API 端点的 swagger api 文档，那么我建议您使用 drf-yasg。

在编写 JSON API 时，不支持开箱即用，但有 sample code 可以相对轻松地启动和运行它。进行此更改后，所有端点都将自动记录。

This Github Gist 包含我们应用程序的代码，希望在此功能完全开发之前对您有所帮助。

【讨论】：

我的经验是，drf-yasg 绝对是一种改进，解决了 mimetype 问题，但仍然呈现扁平的请求和响应正文字典。我发现的唯一方法是为每个调用定义单独的（和嵌套的）序列化程序来复制 JSON API 调用的模式，并告诉drf-yasg 使用这些而不是应用程序使用的那些。我有点希望你用更少的手工也能达到同样的效果，在这种情况下我很好奇如何:)
@ZeusttheUnoobian 发布这项工作的开发人员不再与我们在一起，因此我没有了解所有细节。在答案中添加了更多细节，包括我们的示例代码。让我知道你是怎么做的。
至少乍一看，这看起来像更多的代码，但没有我做的那么hacky。我想我喜欢它！这看起来可能是 djangorestframework-jsonapi 和 drf-yasg 之间的项目独立胶水库，几乎不需要修改。赞一个！

【解决方案2】：

正如您在自己的答案中指出的那样，还有另一种选择：drf-yasg。这是一个很棒的包但不支持开箱即用的 JSON API 架构。

这样你最好使用drf-yasg-json-api 通过提供所有必要的现场检查器将JSON API支持添加到drf-yasg，你只需要稍微扩展你的SWAGGER_SETTINGS。 p>

免责声明：我是这个包的作者。

【讨论】：