API 文档生成器 mewayz

Mewayz 中的 API 文档生成器

API 文档生成器附加组件为 Mewayz REST API 提供应用内可浏览参考。

Mewayz-原始模块 — 没有 Mewayz 上游。文档由包源编写，位于 packages/mewayz/ApiDocsGenerator/。

在产品中

简介

API 文档生成器附加组件为运营商和第三方开发人员提供了 Mewayz REST API 的单页可搜索参考。它相当于 Swagger UI 的应用内版本 - 每个记录的端点、请求模式、响应模式和示例有效负载都在管理员内部呈现，因此开发人员无需离开平台即可进行集成。

文档表面是 模式驱动：该包从以下位置加载预构建的 JSON 文件 src/documentation/ （每个域一个：items.json、project.json、account.json 等），由 master 键入 config.json 列出了要呈现的域及其显示名称。这意味着文档对于实际合约来说是准确的——它们不会偏离路由，因为每个版本都会将路由和匹配的 JSON 模式一起发布。

如何启用该模块

要设置 API 文档生成器附加组件，您可以点击以下链接：设置附加组件。

该附加组件的门控是 PlanModuleCheck:ApiDocsGenerator。通过以下方式在计划或每个租户上激活它 附加组件 管理页面；激活后，侧边栏中会出现“API 文档”条目。

如何访问 API 文档

登录Mewayz并导航至 API文档 在侧边栏中。
单页参考加载于 /api-docs。该路线是auth-

门控（web + auth + verified + PlanModuleCheck），因此匿名访问者将被重定向到登录页面。

引用按域分组。每个域列出了每个

包含 HTTP 动词、路径、所需标头、请求正文架构和示例响应的可用端点。

向 Mewayz API 进行身份验证

此处记录的所有 Mewayz API 端点均受 **Laravel Sanctum** 保护，并且需要在 Authorization 标头。内容类型是通过以下方式强制执行的 api.json 中间件——每个请求都必须包含 Content-Type: application/vnd.api+json （或等效的 JSON 标头）或请求在到达控制器之前被拒绝。

发行代币：

从操作员的个人资料菜单中，打开 API令牌。
点击 创建令牌，命名并立即复制秘密

（秘密只显示一次）。

在每次 API 调用时传递令牌： Authorization: Bearer <token>。

端点覆盖

捆绑的 JSON 模式涵盖以下领域：

用户管理 — /api/users, /api/user/store|update|delete|reset-password|verify
产品与服务 — /api/products, /api/product/create|update|detail|delete，加上类别、税金、单位、仓库库存
项目管理 — /api/projects, /api/project/{id}/task-board、里程碑、错误跟踪
销售和采购发票 — /api/sales-invoice, /api/sales-invoice-return, /api/purchase-invoice, /api/purchase-return
仓库和库存转移 — /api/warehouse, /api/warehouse/product/{warehouse_id}, /api/transfer
销售建议 — /api/sales-proposal
人力资源管理 — /api/employees, /api/attendance, /api/leave-application, /api/payrolls
客户关系管理与销售线索 — /api/leads, /api/deal/*, /api/pipeline, /api/lead-stage, /api/labels, /api/sources
会计 — /api/chart-of-accounts, /api/customers, /api/vendors, /api/bank-accounts, /api/revenues, /api/expenses
销售点 — /api/pos

权限

侧边栏中 API 文档条目的可见性由 Spatie 权限控制 manage-api-docs。没有此权限的操作员看不到菜单条目，如果访问，则会收到 403 /api-docs 直接。

操作员注意事项

文档是只读今天——没有“尝试一下”

按钮从文档页面实时执行调用。（使用 Postman 等工具或 curl 针对记录的端点进行测试。）

JSON 模式位于源代码管理中

packages/mewayz/ApiDocsGenerator/src/documentation/。当新的 API 端点发布时，会在同一版本中添加或扩展匹配的 JSON 文件。

白标租户会自动看到文档表面的范围

他们自己的品牌名称和基本网址；无需为每个租户维护单独的文档。