如何在Django REST框架中使用Swagger API

风声之家 2021-04-09

展开全文

WEB前端开发社区今天

在本教程的这里，我将向您展示如何在Django REST框架中使用Swagger API。Swagger API为REST API端点提供了结构良好的文档，因此新手可以说如何在不了解其内部实现的情况下测试REST API。

本质上，Swagger做的是简单但非常强大的事情：通过添加一些附加注释，它会生成REST API描述，例如HTTP方法，路径/查询/表单参数，响应，HTTP错误代码等），甚至提供了一个简单的Web UI来对您的API的REST调用。

Swagger规范是描述RESTful API的强大定义格式，它创建RESTful接口，通过有效地映射与之关联的所有资源和操作来轻松开发和使用API。它易于学习，与语言无关，并且可以人工和机器可读。

先决条件

Python 3.8.5，Django 3.0.8，REST框架（pip install djangorestframework），Swagger（pip install django-rest-swagger）

假定您已经在系统上安装并配置了Python。

下一个任务是安装Django。首选方法是使用命令pip install Django进行安装。您可以阅读有关Django安装的更多详细信息。

我们将使用MySQL数据库服务器作为存储数据的持久系统，因此您需要阅读教程，了解如何使用django设置MySQL以执行SQL语句。

另外，您需要使用命令pip install django-rest-swagger安装Swagger模块。

我建议您先阅读Django MySQL REST CRUD API示例教程，然后再继续学习。因为此示例恰好遵循该教程。在此示例中，除了REST API CRUD示例之外，我还添加了Swagger API。

在本示例中，我将不展示项目的每个部分，因为我将与现有项目一起工作，但是我将介绍重要的更改。您以后总是可以从本教程底部的链接从我的Github帐户下载完整的项目。

项目设置

我们需要做的第一件事是创建项目目录。项目名称为djangomysqlrestcrudswagger，我们将使用以下命令创建该项目。

<span class="code-snippet_outer">django-admin startproject djangomysqlrestcrudswagger</span>

下一步是在项目内部创建一个应用程序以执行CRUD操作。使用以下命令创建一个名为restcrudswagger的应用程序。

<span class="code-snippet_outer">django-admin startapp restcrudswagger</span>

现在，我们需要将此restcrudswagger应用程序添加到项目中。因此，编辑文件djangomysqlrestcrudswagger / djangomysqlrestcrudswagger / settings.py并将以下行添加到INSTALLED_APPS部分：

<span class="code-snippet_outer"><span class="code-snippet__attribute">INSTALLED_APPS</span> = [</span></code><code><span class="code-snippet_outer">    ...</span></code><code><span class="code-snippet_outer">    <span class="code-snippet__string">'rest_framework_swagger'</span>,</span></code><code><span class="code-snippet_outer">    <span class="code-snippet__string">'restcrudswagger.apps.RestcrudswaggerConfig'</span>,</span></code><code><span class="code-snippet_outer">]</span>

上一行是使用文件djangomysqlrestcrudswagger / restcrudswagger / apps.py构成的。您将在此文件中看到名为=’restcrudswagger’的RestcrudswaggerConfig类。

您需要将以下行添加到上述文件（settings.py）中，否则您将看到错误“ /’AutoSchema’对象的AttributeError没有属性’get_link’”。

<span class="code-snippet_outer"><span class="code-snippet__attr">REST_FRAMEWORK</span> = { <span class="code-snippet__string">'DEFAULT_SCHEMA_CLASS'</span>: <span class="code-snippet__string">'rest_framework.schemas.coreapi.AutoSchema'</span> }</span>

URLS

接下来，我将更改URL方案以添加用于REST文档的Swagger API。将以下代码写入文件 djangomysqlrestcrudswagger / djangomysqlrestcrudswagger / urls.py中。

<span class="code-snippet_outer"><span class="code-snippet__keyword">from</span> rest_framework_swagger.views <span class="code-snippet__keyword">import</span> get_swagger_view</span></code><code><span class="code-snippet_outer"></span></code><code><span class="code-snippet_outer">schema_view = get_swagger_view(title=<span class="code-snippet__string">'User API'</span>)</span></code><code><span class="code-snippet_outer"></span></code><code><span class="code-snippet_outer">urlpatterns = [</span></code><code><span class="code-snippet_outer">    url(<span class="code-snippet__string">'^$'</span>, schema_view)</span></code><code><span class="code-snippet_outer">]</span>

带有源代码的整个文件如下：

<span class="code-snippet_outer"><span class="code-snippet__keyword">from</span> django.urls <span class="code-snippet__keyword">import</span> include, path</span></code><code><span class="code-snippet_outer"><span class="code-snippet__keyword">from</span> rest_framework <span class="code-snippet__keyword">import</span> routers</span></code><code><span class="code-snippet_outer"><span class="code-snippet__keyword">from</span> restcrudswagger <span class="code-snippet__keyword">import</span> views</span></code><code><span class="code-snippet_outer"><span class="code-snippet__keyword">from</span> django.conf.urls <span class="code-snippet__keyword">import</span> url</span></code><code><span class="code-snippet_outer"><span class="code-snippet__keyword">from</span> rest_framework_swagger.views <span class="code-snippet__keyword">import</span> get_swagger_view</span></code><code><span class="code-snippet_outer"></span></code><code><span class="code-snippet_outer">router = routers.DefaultRouter()</span></code><code><span class="code-snippet_outer">router.register(<span class="code-snippet__string">r'users'</span>, views.UserViewSet)</span></code><code><span class="code-snippet_outer"></span></code><code><span class="code-snippet_outer">schema_view = get_swagger_view(title=<span class="code-snippet__string">'User API'</span>)</span></code><code><span class="code-snippet_outer"></span></code><code><span class="code-snippet_outer">urlpatterns = [</span></code><code><span class="code-snippet_outer">    url(<span class="code-snippet__string">'^$'</span>, schema_view),</span></code><code><span class="code-snippet_outer">    url(<span class="code-snippet__string">r'^'</span>, include(router.urls))</span></code><code><span class="code-snippet_outer">]</span>

Swagger UI Template

接下来，您需要创建Swagger模板文件，该文件将在您访问URL时呈现。

以下内容被写入djangomysqlrestcrudswagger / restcrudswagger / templates / rest_framework_swagger / index.html。

<span class="code-snippet_outer"><span class="code-snippet__meta"><!DOCTYPE html></span></span></code><code><span class="code-snippet_outer"><span class="code-snippet__tag"><<span class="code-snippet__name">html</span>></span></span></code><code><span class="code-snippet_outer">  <span class="code-snippet__tag"><<span class="code-snippet__name">head</span>></span></span></code><code><span class="code-snippet_outer">    <span class="code-snippet__tag"><<span class="code-snippet__name">title</span>></span>Swagger<span class="code-snippet__tag"></<span class="code-snippet__name">title</span>></span></span></code><code><span class="code-snippet_outer">    <span class="code-snippet__tag"><<span class="code-snippet__name">meta</span> <span class="code-snippet__attr">charset</span>=<span class="code-snippet__string">"utf-8"</span>/></span></span></code><code><span class="code-snippet_outer">    <span class="code-snippet__tag"><<span class="code-snippet__name">meta</span> <span class="code-snippet__attr">name</span>=<span class="code-snippet__string">"viewport"</span> <span class="code-snippet__attr">content</span>=<span class="code-snippet__string">"width=device-width, initial-scale=1"</span>></span></span></code><code><span class="code-snippet_outer">    <span class="code-snippet__tag"><<span class="code-snippet__name">link</span> <span class="code-snippet__attr">rel</span>=<span class="code-snippet__string">"stylesheet"</span> <span class="code-snippet__attr">type</span>=<span class="code-snippet__string">"text/css"</span> <span class="code-snippet__attr">href</span>=<span class="code-snippet__string">"//unpkg.com/swagger-ui-dist@3/swagger-ui.css"</span> /></span></span></code><code><span class="code-snippet_outer">  <span class="code-snippet__tag"></<span class="code-snippet__name">head</span>></span></span></code><code><span class="code-snippet_outer">  <span class="code-snippet__tag"><<span class="code-snippet__name">body</span>></span></span></code><code><span class="code-snippet_outer">    <span class="code-snippet__tag"><<span class="code-snippet__name">div</span> <span class="code-snippet__attr">id</span>=<span class="code-snippet__string">"swagger-ui"</span>></span><span class="code-snippet__tag"></<span class="code-snippet__name">div</span>></span></span></code><code><span class="code-snippet_outer">    <span class="code-snippet__tag"><<span class="code-snippet__name">script</span> <span class="code-snippet__attr">src</span>=<span class="code-snippet__string">"//unpkg.com/swagger-ui-dist@3/swagger-ui-bundle.js"</span>></span><span class="code-snippet__tag"></<span class="code-snippet__name">script</span>></span></span></code><code><span class="code-snippet_outer">    <span class="code-snippet__tag"><<span class="code-snippet__name">script</span>></span></span></code><code><span class="code-snippet_outer">    <span class="code-snippet__keyword">const</span> ui = SwaggerUIBundle({</span></code><code><span class="code-snippet_outer">        <span class="code-snippet__attr">url</span>: <span class="code-snippet__string">"{% url schema_url %}"</span>,</span></code><code><span class="code-snippet_outer">        <span class="code-snippet__attr">dom_id</span>: <span class="code-snippet__string">'#swagger-ui'</span>,</span></code><code><span class="code-snippet_outer">        <span class="code-snippet__attr">presets</span>: [</span></code><code><span class="code-snippet_outer">          SwaggerUIBundle.presets.apis,</span></code><code><span class="code-snippet_outer">          SwaggerUIBundle.SwaggerUIStandalonePreset</span></code><code><span class="code-snippet_outer">        ],</span></code><code><span class="code-snippet_outer">        <span class="code-snippet__attr">layout</span>: <span class="code-snippet__string">"BaseLayout"</span></span></code><code><span class="code-snippet_outer">      })</span></code><code><span class="code-snippet_outer"><span class="code-snippet__tag"></<span class="code-snippet__name">script</span>></span></span></code><code><span class="code-snippet_outer">  <span class="code-snippet__tag"></<span class="code-snippet__name">body</span>></span></span></code><code><span class="code-snippet_outer"><span class="code-snippet__tag"></<span class="code-snippet__name">html</span>></span></span>

已知问题

如果在访问URL http：// localhost：8000时看到以下错误，则可以编辑路径中提到的以下文件，如下图所示：