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.
This commit is contained in:
parent
a01bfabfba
commit
91a1523d71
8 changed files with 231 additions and 88 deletions
58
docs/howtos/maintenance.md
Normal file
58
docs/howtos/maintenance.md
Normal file
|
|
@ -0,0 +1,58 @@
|
|||
# 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](https://the-guild.dev/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:
|
||||
|
||||
```bash
|
||||
npm run codegen
|
||||
```
|
||||
|
||||
### Testing
|
||||
|
||||
We use [Jest](https://jestjs.io/) for unit and integration testing.
|
||||
|
||||
- **Test Directory**: `src/test/`
|
||||
- **Execution**:
|
||||
```bash
|
||||
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:
|
||||
|
||||
1. Check for updates: `npm outdated`
|
||||
2. Update packages: `npm update`
|
||||
3. 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:
|
||||
```bash
|
||||
docker build -t zabbix-graphql-api --build-arg API_VERSION=$(git describe --tags --always) .
|
||||
```
|
||||
|
||||
---
|
||||
**Related Reference**: [Project Configuration Reference](../../README.md#configuration)
|
||||
**Related Cookbook**: [Extending the Schema](./cookbook.md#recipe-extending-schema-with-a-new-device-type)
|
||||
Loading…
Add table
Add a link
Reference in a new issue