简介
Swagger 是一个由 SmartBear Software 维护的开放源代码项目，它用于描述 RESTful Web Services 的结构、产生文档以及动态生成客户端的 SDK，使得 API 的开发、测试和维护更加简单。
而 @mccue/django-swagger 是基于 Django REST Framework API 文档生成工具 swagger-jsdoc 开发的一个 npm 包，可以帮助前端工程师快速生成 API 的文档。
本文将详细介绍如何使用 @mccue/django-swagger。
步骤
1. 安装 @mccue/django-swagger
在项目的根目录下打开终端并输入以下命令：
npm install @mccue/django-swagger --save-dev
2. 配置 swagger-jsdoc
在项目的根目录下创建一个名为 swagger.json 的文件，并添加以下内容：
-- -------------------- ---- -------
-
---------- ------
------- -
---------- --------
-------- ----- --- -------
-------------- ----- --- -------------
---------- -
------- ----- ------
-------- ------------------------
-
--
------- -----------------
----------- -------
------- -
-
------- ----- --- ------
-------------- ----- --- ------------
-
--
---------- -
------
--
-------- ---
---------------------- --
-将其中的 "Your API Title"、"Your API Description"、"Your Name"、"your-email@example.com"、"Your Tag Name" 和 "Your Tag Description" 替换成实际的信息。
然后在项目的根目录下创建一个名为 swagger.js 的文件，并添加以下内容：
-- -------------------- ---- ------- ----- ------------ - ------------------------- ----- ----------------- - -------------------------- ----- ------- - - ------------------ ------------------ ----- --------------- -- -------------- - ----------------------
将其中的 "./api/*.js" 替换成实际的 API 所在的文件路径。
3. 配置 webpack
在项目的 webpack 配置文件中添加以下内容：
-- -------------------- ---- -------
----- ---- - ----------------
----- ------- - -------------------
----- ------ - ---------------------
-------------- - -
-- ---
-------- -
-- ---
--- ----------------------
------- -----------------------
---
--
-- ---
-4. 示例代码
假设我们在项目中有一个名为 user 的 API，位于 ./api/user.js，包含以下代码：
-- -------------------- ---- ------- --- - -------- - ------------------ - ---- - ----- ------ - ------------ --- ---- -- -- - --------- - - ---------------- - ----------- - - ----- -- - ------------ ------ -- - --- ---- - --------- ---- - ----- ------- - ---------- - ---- - ------------ ---- ------ - ------- - ----- -------------------- - ------------ - ----- - ----- ------ - ----------- - --- - ----- ------- - ----- - ----- ------ - ------ - ----- ------ -- ----- ----------- - ----- ---- -- - -- --- -- -------------- - - ------------ --
然后我们在前端的代码中可以通过以下一段代码来获取该 API 的文档：
console.log(SW_DOC.apis.filter((api) => api.url === '/api/v1/user/{id}'));效果展示
效果展示请参考 Swagger 官网上的示例：https://petstore.swagger.io/#/pet/getPetById
总结
在前后端分离的开发模式下，快速生成 API 文档是非常必要的。@mccue/django-swagger 可以帮助前端工程师快速地生成 API 文档，使得前后端更加紧密地协作。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/6005668881e8991b448e2c11