Grocy 1.9.0 REST API 文档化里程碑内置 Swagger UI 与 OpenAPI 数据模型实战指南【免费下载链接】grocyERP beyond your fridge - Grocy is a web-based self-hosted groceries household management solution for your home项目地址: https://gitcode.com/GitHub_Trending/gr/grocyGrocy 是一个基于 Web 的自托管家庭杂物与库存管理ERP beyond your fridge解决方案。在其 1.9.0 版本2018-04-21 发布见 changelog/18_1.9.0_2018-04-21.md中项目完成了一项对开发者意义深远的工作正式将 REST API 与底层数据模型文档化并在应用内集成了 Swagger UI 浏览器。本文将基于该变更及仓库源码系统讲解如何访问这份 API 文档、规范文件的生成机制、API 的认证与端点组织方式以及通用实体接口的查询过滤语法帮助你快速上手基于 Grocy REST API 做二次开发与自动化集成。1.9.0 变更背景API 从能用走向可查1.9.0 的 changelog 只有一条但信息量极大Documented the REST API and data model, see the integrated instance of Swagger UI at/api这意味着 Grocy 在 1.9.0 之前已经拥有完整的 REST API但缺乏配套文档本次版本把接口契约OpenAPI 规范与数据模型实体 Schema一并整理成机器可读的规范文件并直接嵌入 Web 应用用户打开自己的 Grocy 实例即可浏览与调试所有接口。这一工作的后续演进也验证了它的基石作用1.9.1见 changelog/19_1.9.1_2018-04-22.md紧接着Added validation of all API requests and improved Swagger/OpenAPI description对所有 API 请求增加校验并进一步完善 OpenAPI 描述1.9.2见 changelog/20_1.9.2_2018-04-22.md新增按条形码对接外部服务查询产品的插件系统同样依赖稳定的 API 契约。可以说1.9.0 是 Grocy 对外开放能力的分水岭从此 API 不再需要阅读源码才能理解而是自文档化的。访问内置 Swagger UI/api路径按 changelog 的指引安装并启动 Grocy 1.9.0 后直接访问你的实例根地址下的/api例如https://your-grocy.example/api即可打开集成的 Swagger UI 页面。从路由注册看见 routes.php$group-get(/api, [OpenApiController::class, DocumentationUi]); $group-get(/manageapikeys, [OpenApiController::class, ApiKeysList]); $group-get(/manageapikeys/new, [OpenApiController::class, CreateNewApiKey]);/api由OpenApiController::DocumentationUi处理渲染视图 views/openapiui.blade.php。该视图加载了swagger-ui-dist的 CSS 与 JS 资源并引入swagger-ui-standalone-preset随后通过 public/viewjs/openapiui.js 以Grocy.OpenApi.SpecUrl指向/api/openapi/specification初始化 Swagger UI 界面。页面标题为 REST API browser并通过robots元标签设置为noindex,nofollow避免被搜索引擎收录内部文档页。在 Swagger UI 中你可以看到 Grocy REST API 的完整端点清单、请求/响应 Schema、以及每个端点的参数说明并可以直接在浏览器里试调用Try it out。这是理解 Grocy 数据模型最直观的入口。规范之源grocy.openapi.json支撑这份在线文档的是仓库根目录下的 grocy.openapi.json——一份约 6000 行的OpenAPI 3.1.0规范文件。其info块声明了接口标题 Grocy REST API并说明了两条重要信息认证方式通过 API 密钥请求头GROCY-API-KEY或同名查询参数完成认证API 密钥可在 Manage API keys 页面管理额外通道来自前端经 session cookie 登录的请求同样有效。规范中的tags数组给出了 API 的整体分类对应 Swagger UI 左侧的分组导航Tag说明Generic entity interactions一组直接暴露的通用实体交互接口便于快速增删改查System系统信息、时间、配置、本地化等User management用户管理与权限Current user当前登录用户及其设置Stock库存入库、出库、转移、盘点、合并等Stock by-barcode按商品条形码访问的库存端点替代按 id 访问Recipes食谱满足度、按食谱消费等Chores家务任务及其执行记录Batteries电池充放电周期Tasks任务完成/撤销CalendariCal 日历订阅与分享链接Files文件上传、读取、删除Print打印如购物清单热敏打印components/schemas部分则定义了数据模型从DbChangedTimeResponse、Error400等通用响应对象到ExposedEntity、ExposedEntityNoEdit、ExposedEntityNoDelete、ExposedEntityNoListing等实体枚举再到各业务对象的字段结构构成了完整的数据模型文档。动态生成规范DocumentationSpec源码剖析静态 JSON 文件只是模板真正对外服务的规范是运行时动态生成的。核心实现在 controllers/Api/OpenApiController.php 的DocumentationSpec方法它通过GetOpenApispec()定义于 controllers/Api/BaseApiController.php读取并解析grocy.openapi.json随后做四处关键修补版本号注入调用ApplicationService::GetInstalledVersion()读取实际安装版本写入spec-info-version保证文档与运行版本一致API 密钥管理链接注入将规范描述中的PlaceHolderManageApiKeysUrl占位符替换为当前实例的/manageapikeys地址经UrlManager::ConstructUrl生成尊重配置的BASE_URL服务器地址注入将spec-servers[0]-url设为当前实例的/api路径实体枚举动态扩展基于UserfieldsService::GetEntities()返回的用户自定义实体动态扩充ExposedEntity_IncludingUserEntities等枚举同时由ExposedEntity与ExposedEntityNoEdit/ExposedEntityNoDelete/ExposedEntityNoListing的交集差集派生出不可编辑/不可删除/不可列举的各类变体枚举并额外将stock实体加入可编辑枚举源码注释说明库存条目通常不可直接编辑但其对应的 Userfields 可编辑。也就是说用户通过管理界面新增的自定义实体Userfields会自动出现在 API 文档与通用实体接口中无需重启或手工改文档——这是文档化与可扩展数据模型结合的典型设计。对应的规范 JSON 由路由GET /api/openapi/specification提供routes.php前端 Swagger UI 正是加载该地址获取规范。API 认证GROCY-API-KEY请求头与查询参数根据 OpenAPI 规范info.description的说明REST API 的认证方式为 API 密钥。其实现位于 middleware/Auth/ApiKeyAuthMiddleware.php校验顺序为优先检查请求头默认名为GROCY-API-KEY实际名称来自容器配置ApiKeyHeaderName调用ApiKeyService::IsValidApiKey()验证请求头缺失时回退检查同名查询参数源码注释明确提示不推荐但支持针对calendar-ical路由的特殊用途密钥API_KEY_TYPE_SPECIAL_PURPOSE_CALENDAR_ICAL通过secret查询参数校验 iCal 订阅链接。校验通过后中间件通过ApiKeyService::GetUserByApiKey()返回对应的用户对象后续请求以该用户身份与权限执行。API 密钥的获取登录 Web 界面后访问/manageapikeys即 Swagger UI 描述中链接指向的 Manage API keys 页面由OpenApiController::ApiKeysList渲染controllers/Api/OpenApiController.php。非管理员仅能查看自己的密钥管理员可见全部点击/manageapikeys/newCreateNewApiKey可创建新密钥创建后重定向回列表页并定位到新密钥controllers/Api/OpenApiController.php。一个典型的调用方式基于源码确认的认证机制# 通过请求头携带 API 密钥 curl -H GROCY-API-KEY: 你的API密钥 https://your-grocy.example/api/system/info # 或通过同名查询参数不推荐密钥会出现在 URL 中 curl https://your-grocy.example/api/stock?GROCY-API-KEY你的API密钥端点全览从 System 到 Stock by-barcode/api路由组在 routes.php 中统一注册且整组挂载了CorsMiddleware与JsonMiddleware保证跨域访问与 JSON 响应。主要端点分类如下System系统GET /system/info版本、PHP/SQLite 运行时信息、GET /system/time、GET /system/db-changed-time数据库最后变更时间前端轮询同步依赖它、GET /system/config全部配置项键值对、POST /system/log-missing-localization、GET /system/localization-strings。Stock库存核心模块GET /stock当前库存、GET /stock/volatile易变质库存、商品详情/stock/products/{productId}、库存条目/stock/entries、以及入库add、出库consume、转移transfer、盘点inventory、开封open、合并merge、撤单undo等操作型端点同时提供按条形码访问的整套by-barcode端点如POST /stock/products/by-barcode/{barcode}/add、价格历史、打印标签、外部条形码查询等。Recipes / Chores / Batteries / Tasks食谱满足度GET /recipes/{recipeId}/fulfillment、按食谱消费、家务执行POST /chores/{choreId}/execute、电池充电POST /batteries/{batteryId}/charge、任务完成POST /tasks/{taskId}/complete等。Calendar / Files / PrintiCal 订阅GET /calendar/ical、文件上传/读取/删除PUT|GET|DELETE /files/{group}/{fileName}、热敏打印GET /print/shoppinglist/thermal。Generic entity interactions通用实体交互/objects/{entity}系列提供对任意可暴露实体的通用 CRUD见下节。通用实体接口与查询过滤语法对于GET /api/objects/{entity}这类列表接口controllers/Api/BaseApiController.php 提供了统一的查询参数语法使 API 具备迷你查询语言能力参数作用示例query过滤条件可重复格式为字段运算符值querydue_date2026-01-01limit/offset分页limit 缺省时取 -1即不限制limit10offset20order排序格式字段:asc/desc缺省 ascordername:desc支持的运算符源码PATTERN_OPERATOR与FilterData的 switch 分支运算符含义SQL 映射等于field ?值为null时追加OR field IS NULL!不等于field ! ?~包含模糊匹配field LIKE %value%!~不包含field NOT LIKE %value%///比较对应比较运算§正则匹配field REGEXP ?例如查询所有即将过期的库存条目curl -H GROCY-API-KEY: 你的API密钥 \ https://your-grocy.example/api/objects/stock?querydue_date2026-01-01orderdue_date:asclimit20需要注意的是自 1.9.1 起所有 API 请求都经过统一校验changelog 明确记载非法查询语法会返回错误因此上述语法需严格遵循。小结从 1.9.0 开始的文档化 API之路Grocy 1.9.0 将 REST API 与数据模型正式文档化并集成 Swagger UI 于/api其价值体现在三层对内自解释OpenAPI 规范grocy.openapi.json随版本动态生成版本号、服务器地址、API 密钥管理链接、用户自定义实体枚举均由运行时注入controllers/Api/OpenApiController.php对外可编程统一的GROCY-API-KEY认证middleware/Auth/ApiKeyAuthMiddleware.php与通用实体查询语法controllers/Api/BaseApiController.php让脚本、自动化任务与第三方应用可以稳定地读写家庭库存数据持续演进1.9.1 的请求校验、1.9.2 的条形码插件系统都建立在 1.9.0 打下的 API 契约之上。对开发者而言最直接的行动是部署或启动你的 Grocy 实例访问/api打开 REST API browser在/manageapikeys生成一个 API 密钥然后对着文档逐个试调库存、购物清单、家务与电池接口——这份随仓库自带的活文档就是你深入 Grocy 二次开发的起点。【免费下载链接】grocyERP beyond your fridge - Grocy is a web-based self-hosted groceries household management solution for your home项目地址: https://gitcode.com/GitHub_Trending/gr/grocy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Grocy 1.9.0 REST API 文档化里程碑内置 Swagger UI 与 OpenAPI 数据模型实战指南【免费下载链接】grocyERP beyond your fridge - Grocy is a web-based self-hosted groceries household management solution for your home项目地址: https://gitcode.com/GitHub_Trending/gr/grocyGrocy 是一个基于 Web 的自托管家庭杂物与库存管理ERP beyond your fridge解决方案。在其 1.9.0 版本2018-04-21 发布见 changelog/18_1.9.0_2018-04-21.md中项目完成了一项对开发者意义深远的工作正式将 REST API 与底层数据模型文档化并在应用内集成了 Swagger UI 浏览器。本文将基于该变更及仓库源码系统讲解如何访问这份 API 文档、规范文件的生成机制、API 的认证与端点组织方式以及通用实体接口的查询过滤语法帮助你快速上手基于 Grocy REST API 做二次开发与自动化集成。1.9.0 变更背景API 从能用走向可查1.9.0 的 changelog 只有一条但信息量极大Documented the REST API and data model, see the integrated instance of Swagger UI at/api这意味着 Grocy 在 1.9.0 之前已经拥有完整的 REST API但缺乏配套文档本次版本把接口契约OpenAPI 规范与数据模型实体 Schema一并整理成机器可读的规范文件并直接嵌入 Web 应用用户打开自己的 Grocy 实例即可浏览与调试所有接口。这一工作的后续演进也验证了它的基石作用1.9.1见 changelog/19_1.9.1_2018-04-22.md紧接着Added validation of all API requests and improved Swagger/OpenAPI description对所有 API 请求增加校验并进一步完善 OpenAPI 描述1.9.2见 changelog/20_1.9.2_2018-04-22.md新增按条形码对接外部服务查询产品的插件系统同样依赖稳定的 API 契约。可以说1.9.0 是 Grocy 对外开放能力的分水岭从此 API 不再需要阅读源码才能理解而是自文档化的。访问内置 Swagger UI/api路径按 changelog 的指引安装并启动 Grocy 1.9.0 后直接访问你的实例根地址下的/api例如https://your-grocy.example/api即可打开集成的 Swagger UI 页面。从路由注册看见 routes.php$group-get(/api, [OpenApiController::class, DocumentationUi]); $group-get(/manageapikeys, [OpenApiController::class, ApiKeysList]); $group-get(/manageapikeys/new, [OpenApiController::class, CreateNewApiKey]);/api由OpenApiController::DocumentationUi处理渲染视图 views/openapiui.blade.php。该视图加载了swagger-ui-dist的 CSS 与 JS 资源并引入swagger-ui-standalone-preset随后通过 public/viewjs/openapiui.js 以Grocy.OpenApi.SpecUrl指向/api/openapi/specification初始化 Swagger UI 界面。页面标题为 REST API browser并通过robots元标签设置为noindex,nofollow避免被搜索引擎收录内部文档页。在 Swagger UI 中你可以看到 Grocy REST API 的完整端点清单、请求/响应 Schema、以及每个端点的参数说明并可以直接在浏览器里试调用Try it out。这是理解 Grocy 数据模型最直观的入口。规范之源grocy.openapi.json支撑这份在线文档的是仓库根目录下的 grocy.openapi.json——一份约 6000 行的OpenAPI 3.1.0规范文件。其info块声明了接口标题 Grocy REST API并说明了两条重要信息认证方式通过 API 密钥请求头GROCY-API-KEY或同名查询参数完成认证API 密钥可在 Manage API keys 页面管理额外通道来自前端经 session cookie 登录的请求同样有效。规范中的tags数组给出了 API 的整体分类对应 Swagger UI 左侧的分组导航Tag说明Generic entity interactions一组直接暴露的通用实体交互接口便于快速增删改查System系统信息、时间、配置、本地化等User management用户管理与权限Current user当前登录用户及其设置Stock库存入库、出库、转移、盘点、合并等Stock by-barcode按商品条形码访问的库存端点替代按 id 访问Recipes食谱满足度、按食谱消费等Chores家务任务及其执行记录Batteries电池充放电周期Tasks任务完成/撤销CalendariCal 日历订阅与分享链接Files文件上传、读取、删除Print打印如购物清单热敏打印components/schemas部分则定义了数据模型从DbChangedTimeResponse、Error400等通用响应对象到ExposedEntity、ExposedEntityNoEdit、ExposedEntityNoDelete、ExposedEntityNoListing等实体枚举再到各业务对象的字段结构构成了完整的数据模型文档。动态生成规范DocumentationSpec源码剖析静态 JSON 文件只是模板真正对外服务的规范是运行时动态生成的。核心实现在 controllers/Api/OpenApiController.php 的DocumentationSpec方法它通过GetOpenApispec()定义于 controllers/Api/BaseApiController.php读取并解析grocy.openapi.json随后做四处关键修补版本号注入调用ApplicationService::GetInstalledVersion()读取实际安装版本写入spec-info-version保证文档与运行版本一致API 密钥管理链接注入将规范描述中的PlaceHolderManageApiKeysUrl占位符替换为当前实例的/manageapikeys地址经UrlManager::ConstructUrl生成尊重配置的BASE_URL服务器地址注入将spec-servers[0]-url设为当前实例的/api路径实体枚举动态扩展基于UserfieldsService::GetEntities()返回的用户自定义实体动态扩充ExposedEntity_IncludingUserEntities等枚举同时由ExposedEntity与ExposedEntityNoEdit/ExposedEntityNoDelete/ExposedEntityNoListing的交集差集派生出不可编辑/不可删除/不可列举的各类变体枚举并额外将stock实体加入可编辑枚举源码注释说明库存条目通常不可直接编辑但其对应的 Userfields 可编辑。也就是说用户通过管理界面新增的自定义实体Userfields会自动出现在 API 文档与通用实体接口中无需重启或手工改文档——这是文档化与可扩展数据模型结合的典型设计。对应的规范 JSON 由路由GET /api/openapi/specification提供routes.php前端 Swagger UI 正是加载该地址获取规范。API 认证GROCY-API-KEY请求头与查询参数根据 OpenAPI 规范info.description的说明REST API 的认证方式为 API 密钥。其实现位于 middleware/Auth/ApiKeyAuthMiddleware.php校验顺序为优先检查请求头默认名为GROCY-API-KEY实际名称来自容器配置ApiKeyHeaderName调用ApiKeyService::IsValidApiKey()验证请求头缺失时回退检查同名查询参数源码注释明确提示不推荐但支持针对calendar-ical路由的特殊用途密钥API_KEY_TYPE_SPECIAL_PURPOSE_CALENDAR_ICAL通过secret查询参数校验 iCal 订阅链接。校验通过后中间件通过ApiKeyService::GetUserByApiKey()返回对应的用户对象后续请求以该用户身份与权限执行。API 密钥的获取登录 Web 界面后访问/manageapikeys即 Swagger UI 描述中链接指向的 Manage API keys 页面由OpenApiController::ApiKeysList渲染controllers/Api/OpenApiController.php。非管理员仅能查看自己的密钥管理员可见全部点击/manageapikeys/newCreateNewApiKey可创建新密钥创建后重定向回列表页并定位到新密钥controllers/Api/OpenApiController.php。一个典型的调用方式基于源码确认的认证机制# 通过请求头携带 API 密钥 curl -H GROCY-API-KEY: 你的API密钥 https://your-grocy.example/api/system/info # 或通过同名查询参数不推荐密钥会出现在 URL 中 curl https://your-grocy.example/api/stock?GROCY-API-KEY你的API密钥端点全览从 System 到 Stock by-barcode/api路由组在 routes.php 中统一注册且整组挂载了CorsMiddleware与JsonMiddleware保证跨域访问与 JSON 响应。主要端点分类如下System系统GET /system/info版本、PHP/SQLite 运行时信息、GET /system/time、GET /system/db-changed-time数据库最后变更时间前端轮询同步依赖它、GET /system/config全部配置项键值对、POST /system/log-missing-localization、GET /system/localization-strings。Stock库存核心模块GET /stock当前库存、GET /stock/volatile易变质库存、商品详情/stock/products/{productId}、库存条目/stock/entries、以及入库add、出库consume、转移transfer、盘点inventory、开封open、合并merge、撤单undo等操作型端点同时提供按条形码访问的整套by-barcode端点如POST /stock/products/by-barcode/{barcode}/add、价格历史、打印标签、外部条形码查询等。Recipes / Chores / Batteries / Tasks食谱满足度GET /recipes/{recipeId}/fulfillment、按食谱消费、家务执行POST /chores/{choreId}/execute、电池充电POST /batteries/{batteryId}/charge、任务完成POST /tasks/{taskId}/complete等。Calendar / Files / PrintiCal 订阅GET /calendar/ical、文件上传/读取/删除PUT|GET|DELETE /files/{group}/{fileName}、热敏打印GET /print/shoppinglist/thermal。Generic entity interactions通用实体交互/objects/{entity}系列提供对任意可暴露实体的通用 CRUD见下节。通用实体接口与查询过滤语法对于GET /api/objects/{entity}这类列表接口controllers/Api/BaseApiController.php 提供了统一的查询参数语法使 API 具备迷你查询语言能力参数作用示例query过滤条件可重复格式为字段运算符值querydue_date2026-01-01limit/offset分页limit 缺省时取 -1即不限制limit10offset20order排序格式字段:asc/desc缺省 ascordername:desc支持的运算符源码PATTERN_OPERATOR与FilterData的 switch 分支运算符含义SQL 映射等于field ?值为null时追加OR field IS NULL!不等于field ! ?~包含模糊匹配field LIKE %value%!~不包含field NOT LIKE %value%///比较对应比较运算§正则匹配field REGEXP ?例如查询所有即将过期的库存条目curl -H GROCY-API-KEY: 你的API密钥 \ https://your-grocy.example/api/objects/stock?querydue_date2026-01-01orderdue_date:asclimit20需要注意的是自 1.9.1 起所有 API 请求都经过统一校验changelog 明确记载非法查询语法会返回错误因此上述语法需严格遵循。小结从 1.9.0 开始的文档化 API之路Grocy 1.9.0 将 REST API 与数据模型正式文档化并集成 Swagger UI 于/api其价值体现在三层对内自解释OpenAPI 规范grocy.openapi.json随版本动态生成版本号、服务器地址、API 密钥管理链接、用户自定义实体枚举均由运行时注入controllers/Api/OpenApiController.php对外可编程统一的GROCY-API-KEY认证middleware/Auth/ApiKeyAuthMiddleware.php与通用实体查询语法controllers/Api/BaseApiController.php让脚本、自动化任务与第三方应用可以稳定地读写家庭库存数据持续演进1.9.1 的请求校验、1.9.2 的条形码插件系统都建立在 1.9.0 打下的 API 契约之上。对开发者而言最直接的行动是部署或启动你的 Grocy 实例访问/api打开 REST API browser在/manageapikeys生成一个 API 密钥然后对着文档逐个试调库存、购物清单、家务与电池接口——这份随仓库自带的活文档就是你深入 Grocy 二次开发的起点。【免费下载链接】grocyERP beyond your fridge - Grocy is a web-based self-hosted groceries household management solution for your home项目地址: https://gitcode.com/GitHub_Trending/gr/grocy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
