From 3c3cb7c7534a56a80e2f3861964fd3ed209eedaa Mon Sep 17 00:00:00 2001 From: Andreas Hilbig Date: Wed, 4 Feb 2026 15:36:45 +0100 Subject: [PATCH] docs: audit and fix documentation links and anchors --- README.md | 8 ++++---- docs/howtos/cookbook.md | 14 +++++++------- docs/howtos/local_development.md | 2 +- 3 files changed, 12 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index ef4593c..c28277e 100644 --- a/README.md +++ b/README.md @@ -12,16 +12,16 @@ The Zabbix GraphQL API acts as a wrapper and enhancer for the native Zabbix JSON - *Reference*: `schema/queries.graphql`, `schema/mutations.graphql`, `src/api/start.ts` - **Hierarchical Data Mapping**: Automatic mapping of Zabbix items/tags to nested GraphQL objects - - *Reference*: `src/api/resolver_helpers.ts`, `schema/device_value_commons.graphql`, `docs/sample_all_devices_query.graphql` + - *Reference*: `src/api/resolver_helpers.ts`, `schema/device_value_commons.graphql`, `docs/queries/sample_all_devices_query.graphql` - **Mass Operations**: Import/export capabilities for hosts, templates, and user rights - - *Reference*: `schema/mutations.graphql` (importHosts, importTemplates, importUserRights, etc.), `docs/sample_import_*.graphql` + - *Reference*: `schema/mutations.graphql` (importHosts, importTemplates, importUserRights, etc.), `docs/queries/sample_import_*.graphql` - **Dynamic Schema Extension**: Extend the schema without code changes using environment variables - *Reference*: `src/api/schema.ts`, `samples/extensions/` (sample extensions), `src/common_utils.ts` (ADDITIONAL_SCHEMAS, ADDITIONAL_RESOLVERS) - **Permission System**: Role-based access control using Zabbix template groups - - *Reference*: `schema/api_commons.graphql` (Permission enum, PermissionRequest), `src/api/resolvers.ts` (hasPermissions, userPermissions), `docs/sample_import_permissions_template_groups_mutation.graphql` + - *Reference*: `schema/api_commons.graphql` (Permission enum, PermissionRequest), `src/api/resolvers.ts` (hasPermissions, userPermissions), `docs/queries/sample_import_permissions_template_groups_mutation.graphql` - **Type Safety**: Full TypeScript support with generated types - *Reference*: `codegen.ts`, `src/schema/generated/graphql.ts`, `tsconfig.json`, `package.json` (devDependencies for GraphQL Codegen) @@ -52,7 +52,7 @@ Before you begin, ensure you have met the following requirements: - **Node.js**: Version 24 (LTS) or higher recommended. - **Docker**: Version 27 or higher and **Docker Compose** v2.29 or higher (use `docker compose` instead of `docker-compose`). -- **Zabbix**: A running Zabbix instance (**Zabbix 6.2+ mandatory**) with API access. See [Zabbix Version Compatibility](#-zabbix-version-compatibility) for details. +- **Zabbix**: A running Zabbix instance (**Zabbix 6.2+ mandatory**) with API access. See [Zabbix Version Compatibility](#zabbix-version-compatibility) for details. - **Zabbix Super Admin Token** (for full functionality / privilege escalation). - **Zabbix User Access** (groups and roles depending on your use case). diff --git a/docs/howtos/cookbook.md b/docs/howtos/cookbook.md index b3fe469..c83a559 100644 --- a/docs/howtos/cookbook.md +++ b/docs/howtos/cookbook.md @@ -136,7 +136,7 @@ If you prefer to configure Zabbix manually: #### Method B: Automated Import Execute the `importTemplates` mutation to create the template and items automatically. -> **Reference**: Use the [Sample: Distance Tracker Import](../../docs/queries/sample_import_distance_tracker_template.graphql) for a complete mutation and variables example. +> **Reference**: Use the [Sample: Distance Tracker Import](../queries/sample_import_distance_tracker_template.graphql) for a complete mutation and variables example. ### ✅ Step 4: Verify the Extension Verify that the new type is available and correctly mapped by creating a test host and querying it. @@ -278,7 +278,7 @@ Before configuring the Zabbix template, analyse how often the data source actual ### 🚀 Step 4: Import the Device Template Use the `importTemplates` mutation to create the template. Use **HTTP agent** or **Script** items as master items to fetch data, and **dependent items** to parse the results. -> **Reference**: See the [Sample: Weather Sensor Template Import](../../docs/queries/sample_import_weather_sensor_template.graphql) and [Sample: Ground Value Checker Template Import](../../docs/queries/sample_import_ground_value_checker_template.graphql) for complete mutations. +> **Reference**: See the [Sample: Weather Sensor Template Import](../queries/sample_import_weather_sensor_template.graphql) and [Sample: Ground Value Checker Template Import](../queries/sample_import_ground_value_checker_template.graphql) for complete mutations. **Key Configuration for Weather Sensor**: - **Master Item**: `weather.get` (HTTP Agent) @@ -393,19 +393,19 @@ Restart the API server. ### 🚀 Step 3: Import the Simulated Device Template Use the `importTemplates` mutation to create a template with a **Zabbix Trapper** item. We use the `json_` prefix in the item key to ensure the JSON string is automatically parsed into a `JSONObject`. -> **Reference**: Use the [Sample: Import Simulated BT Template](../../docs/queries/sample_import_simulated_bt_template.graphql) for a complete mutation and variables example. +> **Reference**: Use the [Sample: Import Simulated BT Template](../queries/sample_import_simulated_bt_template.graphql) for a complete mutation and variables example. ### 🚀 Step 4: Push History Data Push GeoJSON data to your simulated device using the `pushHistory` mutation. This allows you to simulate a device moving along a path by providing multiple data points with different timestamps. -> **Reference**: See the [Sample: Push GeoJSON History](../../docs/queries/sample_push_geojson_history.graphql) for a complete example of pushing historical data. +> **Reference**: See the [Sample: Push GeoJSON History](../queries/sample_push_geojson_history.graphql) for a complete example of pushing historical data. ### ✅ Step 5: Verification Verify that the device correctly resolves to the new type and that both the current state and historical data are accessible. - **Create Host**: Use the `importHosts` mutation to create a host (e.g. `Vehicle1`) and link it to the simulated template. - **Query Current State**: Use the `allDevices` query to verify the latest pushed position. - - *Reference*: See the [Sample: Tracked Device Query](../../docs/queries/sample_tracked_device_query.graphql). + - *Reference*: See the [Sample: Tracked Device Query](../queries/sample_tracked_device_query.graphql). - **Query Historical Data**: Use the `exportHostValueHistory` query to retrieve the path history. ```graphql @@ -437,7 +437,7 @@ This recipe shows how to execute a comprehensive query to verify the state and c ### 📋 Prerequisites - Zabbix GraphQL API is running. -- The schema has been extended with the `DistanceTrackerDevice` type (see [Recipe: Extending Schema with a New Device Type](#-recipe-extending-schema-with-a-new-device-type)). Sample extensions can be found in the `samples/extensions` directory. +- The schema has been extended with the `DistanceTrackerDevice` type (see [Recipe: Extending Schema with a New Device Type](#recipe-extending-schema-with-a-new-device-type)). Sample extensions can be found in the `samples/extensions` directory. - At least one host with `deviceType` set to `DistanceTrackerDevice` exists in Zabbix. ### 🛠️ Step 1: Get the Sample Query @@ -561,7 +561,7 @@ query VerifyBulkImport($pattern: String!) { } ``` -For detailed examples of the input structures, refer to [Sample Import Templates](../../docs/queries/sample_import_templates_mutation.graphql) and [Sample Import Hosts](../../docs/queries/sample_import_hosts_mutation.graphql). +For detailed examples of the input structures, refer to [Sample Import Templates](../queries/sample_import_templates_mutation.graphql) and [Sample Import Hosts](../queries/sample_import_hosts_mutation.graphql). --- diff --git a/docs/howtos/local_development.md b/docs/howtos/local_development.md index b906966..99bc147 100644 --- a/docs/howtos/local_development.md +++ b/docs/howtos/local_development.md @@ -85,4 +85,4 @@ Supported tags can be found on the [Zabbix Docker Hub](https://hub.docker.com/u/ --- **Related Guide**: [Technical Maintenance](./maintenance.md) -**Related Reference**: [Zabbix Version Compatibility](../../README.md#-zabbix-version-compatibility) +**Related Reference**: [Zabbix Version Compatibility](../../README.md#zabbix-version-compatibility)