zabbix/zabbix-graphql-api
1
0
Fork 0
Code Pull requests Activity

fix: API_VERSION description

Browse source
This commit is contained in:
Vladimir Svacko 2026-01-28 15:45:08 +01:00
parent 944ae2bfbb
commit 8eb2d2d587
3 changed files with 195 additions and 2 deletions
Download patch file Download diff file Expand all files Collapse all files

4
README.md
View file

@ -101,7 +101,7 @@ npm run start
The GraphQL API will be available at `http://localhost:4000/`
### Available Queries and Mutations
#### Available Queries and Mutations after start
#### Queries
- `apiVersion` - Returns the API build version
@ -572,3 +572,5 @@ For support, please open an issue in the GitHub repository.
## 🔄 API Version
Current API version: ${API_VERSION:-"Not set"}
The API version is automatically set during the Docker build process based on the Git tag or commit hash. During CI/CD deployment (as defined in `.forgejo/workflows/deploy-docker.yaml`), the API_VERSION is determined using `git describe --tags --always`, which creates a version identifier based on the most recent Git tag and the number of commits since that tag. This version information is then embedded into the Docker image as a build argument and becomes accessible through the API_VERSION environment variable at runtime.

74
readme.evaluation.result.md Normal file
View file

@ -0,0 +1,74 @@
# README Evaluation Result
## Executive Summary
The README.md file provides a comprehensive overview of the Zabbix GraphQL API project with good coverage of features, installation, configuration, and usage examples. The document has been recently enhanced with codebase references and detailed explanations of key features.
## Strengths
- Comprehensive coverage of all major features
- Good separation of sections with clear headings
- Detailed environment variable configuration
- Well-structured example for schema extension
- Proper inclusion of Docker deployment instructions
- References to schema and documentation files
- Clear explanation of the permission system
- Good balance between high-level concepts and technical details
## Areas of Concern
### 1. Missing Information
- No mention of the `DRY_RUN` environment variable functionality
- Missing information about the `HOST_TYPE_FILTER_DEFAULT` and `HOST_GROUP_FILTER_DEFAULT` configuration options
- No explanation of the difference between `ZABBIX_AUTH_TOKEN` and `ZABBIX_AUTH_TOKEN_FOR_REQUESTS`
- Missing details about the `FIND_ZABBIX_EDGE_DEVICE_BASE_GROUP_PREFIX` regex pattern
### 2. Incomplete Information
- The "Real-time Subscriptions" feature claims WebSocket support but no actual subscription operations are defined in the schema
- The API version placeholder `${API_VERSION:-"Not set"}` is not properly populated
- No mention of the generated GraphQL types in `src/schema/generated/graphql.ts`
- Missing information about the test structure and how to run individual tests
### 3. Potential Inaccuracies
- The README mentions that the API is published publicly, but the license is AGPL-3.0-only which has specific distribution requirements
- The Docker example uses `your-zabbix-server` placeholder but doesn't explain how to determine the correct URL format
- The example GraphQL queries might not match the exact schema definitions
### 4. Schema Consistency Issues
- The schema contains many types and operations not mentioned in the README
- Some schema types like `Location` are referenced but not explained
- The relationship between Zabbix entities and GraphQL types could be clearer
### 5. Documentation Completeness
- The AGENTS.md file contains important architectural information not reflected in the README
- The codegen.ts file configuration is not explained
- The relationship between different DataSource files is not clear from the README
## Technical Verification
### Features Verification
- ✅ GraphQL Interface: Confirmed in schema files and start.ts
- ✅ Hierarchical Data Mapping: Confirmed in resolver_helpers.ts
- ✅ Mass Operations: Confirmed in mutations.graphql
- ✅ Dynamic Schema Extension: Confirmed in schema.ts
- ✅ Permission System: Confirmed in api_commons.graphql
- ⚠️ Real-time Subscriptions: Infrastructure exists but no actual subscriptions defined
- ✅ Type Safety: Confirmed with codegen and generated types
### Configuration Verification
- ✅ All environment variables in Config class are documented
- ✅ Docker configuration matches Dockerfile
- ✅ Package dependencies match functionality described
### Example Verification
- ✅ Distance tracker example aligns with sample files
- ✅ Import/export operations match schema definitions
- ✅ Permission queries match schema definitions
## Recommendations for Improvement
1. Add missing environment variables and their purposes
2. Clarify the subscription functionality status
3. Expand on the relationship between Zabbix entities and GraphQL types
4. Include more information about the code generation process
5. Add troubleshooting section with common issues
6. Include performance considerations and scaling information
7. Add security best practices section
8. Include backup and recovery procedures

117
readme.improvement.plan.md Normal file
View file

@ -0,0 +1,117 @@
# README Improvement Plan
## Priority 1: Critical Missing Information
### 1.1 Environment Variables
- Add documentation for `DRY_RUN` environment variable and its purpose
- Document `HOST_TYPE_FILTER_DEFAULT` and `HOST_GROUP_FILTER_DEFAULT` configuration options
- Explain the difference between `ZABBIX_AUTH_TOKEN` and `ZABBIX_AUTH_TOKEN_FOR_REQUESTS`
- Add information about `FIND_ZABBIX_EDGE_DEVICE_BASE_GROUP_PREFIX` regex pattern
### 1.2 API Version Information
- Fix the API version placeholder to properly display the current version
- Add information about version compatibility between the API and Zabbix server.
- Tested with Zabbix. 7.4
### 1.3 Subscription Clarification
- Either implement actual subscription operations in the schema or clarify that only infrastructure is provided
- If only infrastructure is provided, update the feature description to be more accurate
## Priority 2: Enhance Existing Sections
### 2.1 Architecture Section
- Add an architecture diagram or detailed explanation based on AGENTS.md
- Include information about the data flow between components
- Explain the role of each DataSource file in the datasources directory
### 2.2 Configuration Section
- Add a complete table of all environment variables with descriptions
- Include default values and required/optional status
- Add examples of production vs development configurations
### 2.3 Schema Relationship Section
- Create a mapping table between Zabbix entities and GraphQL types
- Explain how Zabbix host groups, templates, and items relate to GraphQL objects
- Add information about the Location type and its usage
## Priority 3: Add New Sections
### 3.1 Code Generation Section
- Explain the GraphQL Codegen setup and how to regenerate types
- Document the `codegen.ts` configuration
- Add instructions for updating generated types after schema changes
### 3.2 Troubleshooting Section
- Common connection issues with Zabbix server
- Authentication problems and solutions
- Schema extension troubleshooting
- Performance issues and optimizations
### 3.3 Security Best Practices
- Recommended authentication approaches
- Permission system best practices
- Network security considerations
- API rate limiting and protection
### 3.4 Performance and Scaling
- Performance considerations for large Zabbix installations
- Caching strategies
- Connection pooling recommendations
- Monitoring and observability setup
### 3.5 Backup and Recovery
- Configuration backup procedures
- Schema migration guidelines
- Disaster recovery procedures
## Priority 4: Improve Examples
### 4.1 Complete Examples
- Add more complete examples for each major operation
- Include error handling examples
- Add examples for common use cases beyond the distance tracker
### 4.2 Testing Examples
- Add information about how to run tests
- Include examples of unit and integration tests
- Explain the test structure and how to add new tests
## Priority 5: Documentation Links
### 5.1 Cross-Reference Improvements
- Add links to relevant sections in schema files
- Include references to specific resolver implementations
- Link to related documentation files in the docs directory
### 5.2 External Resources
- Link to official Zabbix API documentation
- Include references to Apollo Server documentation
- Add links to GraphQL best practices
## Priority 6: Maintenance Items
### 6.1 Update Placeholder Values
- Replace all "your-" placeholder values with more descriptive examples
- Add realistic example values for configuration parameters
- Include sample output where appropriate
### 6.2 Version Compatibility Matrix
- Create a matrix showing compatibility between API versions and Zabbix versions
- Include Node.js version compatibility information
- Add information about breaking changes between versions
## Implementation Order
1. Address Priority 1 items first (critical missing information)
2. Update existing sections to be more accurate
3. Add new sections incrementally
4. Enhance examples with more practical use cases
5. Add documentation links and cross-references
6. Perform final review and testing of all examples
## Success Metrics
- All environment variables documented
- Accurate representation of features
- Complete working examples
- Clear architecture and configuration guidance
- Comprehensive troubleshooting information
- Proper cross-references to codebase