Andreas Hilbig 91a1523d71 docs: complete documentation refactoring and structure optimization

This commit finalizes the documentation improvement plan by:
- Centralizing reference material in README.md.
- Creating a dedicated Technical Maintenance guide (docs/howtos/maintenance.md).
- Creating a categorized Sample Queries & Mutations overview (docs/queries/README.md).
- Eliminating redundant information across the doc set (DRY principle).
- Optimizing cross-references between reference documentation and the Cookbook.
- Updating the improvement plan to reflect all tasks as completed.

2026-01-30 15:08:19 +01:00

1.8 KiB

Raw Blame History

Technical Maintenance Guide

This guide covers the technical aspects of maintaining and developing the Zabbix GraphQL API.

🛠️ Development & Maintenance Tasks

Code Generation

The project uses GraphQL Codegen to generate TypeScript types from the GraphQL schema. This ensures type safety and consistency between the schema and the implementation.

Configuration: codegen.ts
Generated Output: src/schema/generated/graphql.ts

How to Regenerate Types

Whenever you modify any .graphql files in the schema/ directory, you must regenerate the TypeScript types:

npm run codegen

Testing

We use Jest for unit and integration testing.

Test Directory: src/test/
Execution:
```
npm run test
```

Adding New Tests

Location: Place new test files in src/test/ with the .test.ts extension.
Coverage: Ensure you cover both successful operations and error scenarios.
Best Practice: If you find a bug, first create a reproduction test in src/test/ to verify the fix.

🔄 Updating Dependencies

To keep the project secure and up-to-date:

Check for updates: npm outdated
Update packages: npm update
Verify with tests: npm run test

🐳 Docker Image Maintenance

The Dockerfile uses a multi-stage build to keep the production image small and secure.

Base Image: Node 24 (LTS)
Build Argument: API_VERSION (used to embed the version into the image)

To build a fresh image locally:

docker build -t zabbix-graphql-api --build-arg API_VERSION=$(git describe --tags --always) .

Related Reference: Project Configuration Reference Related Cookbook: Extending the Schema

1.8 KiB Raw Blame History