简介
swag4k 是一个适用于前端开发的 npm 包，可以为您快速生成符合 OpenAPI 规范 的 API 文档。通过使用 swag4k，您可以轻松地浏览和测试 API，同时也可以分享文档供其他人进行开发工作。
安装
使用 npm 安装 swag4k：
npm install swag4k --save-dev
使用
在您的项目中使用 swag4k 非常简单。只需要在 Express 或 Fastify 应用程序中引入 swag4k 并将其添加到路由处理程序中即可。
使用 Express
在 Express 应用程序中引入 swag4k：
const express = require('express');
const swag4k = require('swag4k');
const app = express();然后，添加一个路由处理程序，并将 swag4k 添加到您的路由处理程序中：
app.get('/api-docs.json', swag4k({
title: 'My API',
version: '1.0.0',
description: 'My API documentation',
}));最后，启动 Express 服务器并访问您的 API 文档：
app.listen(3000, () => {
console.log('App listening on port 3000!');
});使用 Fastify
在 Fastify 应用程序中引入 swag4k：
const fastify = require('fastify');
const swag4k = require('swag4k/fastify');
const app = fastify();然后，添加一个路由处理程序，并将 swag4k 添加到您的路由处理程序中：
app.get('/api-docs.json', swag4k({
title: 'My API',
version: '1.0.0',
description: 'My API documentation',
}));最后，启动 Fastify 服务器并访问您的 API 文档：
app.listen(3000, () => {
console.log('App listening on port 3000!');
});在浏览器中查看 API 文档
默认情况下，swag4k 将 API 文档生成为 JSON 文件。您可以使用 Swagger UI 将此 JSON 文件渲染为漂亮的文档：
-- -------------------- ---- -------
--------- -----
------
------
--------- -----------
-------
------
---- ----------------------
------- ----------------------------------------------------------------------
------- ---------------------------------------------------------------------------------
--------
----- -- - -----------------
---- -----------------
------- --------------
-------- -
-----------------------------
--------------------------
--
------- -------------------
--
---------
-------
-------高级用法
自定义操作 ID
默认情况下，swag4k 会根据路由处理程序的 HTTP 方法和路径生成操作 ID。但是，如果您需要自定义操作 ID，可以在路由处理程序中使用 operationId 选项：
-- -------------------- ---- -------
----------------- --------
------ --- -----
-------- --------
------------ --- --- ---------------
----------- -
--------- -
------------ -----------
---------- -
---- -
------------ ----- -- -------
--
--
--
--
--- ----- ---- -- -
-- ------ --- ------ ----
---路径参数
如果您的路由处理程序中包含路径参数，则可以在 API 文档中为每个路径参数定义名称和类型：
-- -------------------- ---- -------
--------------------- --------
------ --- -----
-------- --------
------------ --- --- ---------------
----------- -
------------ -
---------- -
---- -
------------ ----- -------
--
---- -
------------ ----- --- -------
--
--
----------- -
-
----- -----
--- -------
------------ ----- ----
--------- -----
------- -
----- ---------
--
--
--
--
--
--- ----- ---- -- -
-- ------ --- ---------- ----
---查询参数
如果您的路由处理程序中包含查询参数，则可以在 API 文档中为每个查询参数定义名称、类型和默认值：
-- -------------------- ---- -------
----------------- --------
------ --- -----
-------- --------
------------ --- --- ---------------
----------- -
--------- -
---------- -
---- -
------------ ----- -- -------
--
--
----------- -
-
----- -------
--- --------
------------ ----- --------
--------- ------
------- -
----- ----------
-------- --
--
--
--
--
--
--- ----- ---- -- -
-- ------ --- ------------- ----
---请求体参数
如果您的路由处理程序中包含请求体参数，则可以在 API 文档中为请求体定义模式：
-- -------------------- ---- -------
------------------ --------
------ --- -----
-------- --------
------------ --- --- ---------------
----------- -
----------- -
------------ -
-------- -
------------------- -
------- -
----- ---------
----------- -
----- - ----- -------- --
------ - ----- --------- ------- ------- --
--
--------- -------- ---------
--
--
--
--------- -----
--
---------- -
---- -
------------ ----- ---------
--
---- -
------------ -------- -------
--
--
--
--
--- ----- ---- -- -
-- ------ ---- ------ ----
---响应模式
如果您的 API 路由处理程序返回一些特定的响应模式，则可以在 API 文档中定义这些模式：
-- -------------------- ---- -------
--------------------- --------
------ --- -----
-------- --------
------------ --- --- ---------------
----------- -
------------ -
---------- -
---- -
------------ ----- -------
-------- -
------------------- -
------- -
----- ---------
----------- -
--- - ----- --------- --
----- - ----- -------- --
------ - ----- --------- ------- ------- --
--
--
--
--
--
---- -
------------ ----- --- -------
--
--
----------- -
-
----- -----
--- -------
------------ ----- ----
--------- -----
------- -
----- ---------
--
--
--
--
--
--- ----- ---- -- -
-- ------ --- ---------- ----
---结论
通过使用 swag4k，您可以轻松地为自己的 API 生成文档，并将它们分享给其他人进行开发。虽然本文只介绍了 swag4k 的基本用法，但是 swag4k 也支持许多高级用法，可以满足大多数前端开发人员的需求。希望本文能对您有所帮助！
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/6005536881e8991b448d09d9