接口文档模块
在前后端分离开发及 App 开发模式下，前端与后端工程师需要共同定义接口契约、编写接口文档，并以此为依据进行并行开发。接口文档需要在项目全生命周期内持续维护，确保各方开发人员始终基于一致的接口定义进行协作。
HMX 平台基于 .NET 生态标准的 Swagger / OpenAPI 规范，提供了统一的 API 文档管理能力。Swagger 是一套用于生成、描述、调用和可视化 RESTful 风格 Web 服务的开源框架，已成为 API 文档的事实标准。
HMX 平台 API 文档方案
平台在 网关层统一整合 Swagger 文档 ，各个微服务无需单独配置 API 文档组件。开发者只需在项目中引入公共组件，即可自动完成 API 接口的文档生成与聚合。
核心能力
统一文档入口 ：所有微服务的 API 文档在网关层汇聚，提供单一访问入口，无需分别记忆各个服务的文档地址
自动接口生成 ：基于 .NET 的 XML 注释，自动生成接口描述、参数说明、返回值定义等文档内容
在线调试能力 ：提供可视化的接口调试界面，支持直接在页面上发送请求并查看响应结果
OpenAPI 规范兼容 ：严格遵循 OpenAPI 3.0 规范，可导出为标准格式，便于导入 Postman、Apifox 等第三方工具
接口分组管理 ：支持按服务、按模块、按版本对接口进行分组展示，便于查找与维护
轻量集成 ：公共组件封装了 Swagger 的核心配置，微服务项目仅需添加项目引用即可生效，无需重复编写配置代码
覆盖场景
| 场景 | 说明 |
|---|---|
| Web 前端开发 | 前端工程师通过 API 文档了解接口定义，快速完成页面与数据交互 |
| App 开发 | 移动端工程师基于文档进行接口联调，支持 iOS 与 Android 双端并行开发 |
| 第三方系统集成 | 对外提供标准 OpenAPI 文档，便于合作伙伴或第三方系统对接 |
| 接口测试 | 开发和测试人员可通过在线调试功能快速验证接口逻辑 |
| 接口变更同步 | 代码注释变更后自动更新文档，确保文档与代码一致性 |
设计优势
统一聚合 ：网关层统一管理，避免每个微服务各自暴露文档入口
零配置接入 ：引入公共组件即可生效，各微服务无需额外配置
自动同步 ：接口文档与代码注释同步更新，消除手工维护文档的遗漏与偏差
可视化调试 ：内置在线调试工具，无需借助 Postman 等第三方工具即可完成接口验证
生态兼容 ：支持导出标准 OpenAPI 格式，与各类 API 工具无缝对接