相关学习推荐：python教程
大多数情况下，开发的接口都不是给开发这个接口的人用的，所以如果没有接口文档，别人就无法有哪些接口可以调用，即使知道了接口的 URL，也很难知道接口需要哪些参数，即使知道了这些参数，也可能无法理解这些参数的含义。因此接口文档应该是项目必不可少的配置。
编写接口文档有很多种方式，最为简单直接的方式就是打开一个记事本或者 word 文档，来2源gaodaima#com搞(代@码&网将接口的详细信息和用法写下来，别人就可以参考这个文档来调用接口。这样做虽然简单，但弊端也很明显：一是需要写大量的描述文字，非常枯燥，但其实这些信息在代码中已有体现，有点像是使用自然语言又把代码写了一遍；二是一旦接口有了更新，就必须手动同步更新接口文档，开发人员很容易搞忘这件事，导致接口文档的内容和接口的实际功能不一致。
因为很多接口的信息其实在代码中已有体现，人们自然而然就想到能否直接从写好的代码中自动提取相关信息来生成文档，这样改了代码，接口文档也会自动更新，上面说的两个问题就都可以解决了。
当然写接口文档不是搞文学创作，为了直接从写好的代码中自动提取信息来生成文档，就必须要有一套标准的文档格式，否则工具无法知道要从代码中提取出哪些信息，信息提取之后，也不知道该如何组织这些信息。
经过大家的努力，现在已经有了很多成熟的接口文档标准和生成工具，其中 OpenAPI Specification 就是一个被广泛接收和使用的标准，我们博客接口使用的文档自动化工具，也会基于 OpenAPI 标准从代码中提取文档信息，然后组织为 OpenAPI 的标准格式。
小贴士：
大家更为熟悉的，和 OpenAPI 相关的一个名词是 swagger。Swagger 提供一系列免费开源的 OpenAPI 相关的工具，他们背后的公司是 SMARTBEAR，号称 code quality tools 开发行业的领导者。
OpenAPI 介绍
接口文档不是文学作品，它所需要的内容基本都是固定的。例如对一个 RESTful 风格的接口来说，只需要知道以下这些关键的信息就足够完成对它的调用了。反过来，这些信息也就可以定义一个完整的 RESTful 风格的接口：
- 请求的 HTTP 方法和 URL。
- 接收的参数（包括 URL 中的路径参数、查询参数；HTTP 请求头的参数；HTTP 请求体等参数）。
- 接口返回的内容。
OpenAPI 对以上信息进行了标准化，从而提出了 OpenAPI specification，只要文档内容符合这个标准，OpenAPI 工具就可以对它进行处理，例如可视化文档工具就可以读取文档内容生成 HTML 格式的文档。
注意：
OpenAPI specification 目前最新版本是 3，但目前大部分工具对 2 的支持最好，教程中使用的库仅支持 2。
drf-yasg
drf-yasg 是一个 django 的第三方应用，它可以从 django-rest-framework 框架编写的代码中自动提取接口信息来生成符合 OpenAPI 标准的文档。我们将使用它来生成博客应用的接口文档。
第一步当然是安装 drf-yasg，进入项目根目录，运行命令 ：
Command Tab
Linux/macOS $ pipenv install drf-yasg复制代码
Windows ...\> pipenv install drf-yasg复制代码
然后将 drf-yasg 添加到 INSTALLED_APPS 配置项中：
# filename="blogproject/settings/common.py"INSTALLED_APPS = [ # 其它已添加的应用...
"pure_pagination", # 分页
"haystack", # 搜索
"drf_yasg", # 文档]复制代码
转载请注明原文链接：看透 管理接口文档
