Database Documentation #418
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
- Added `default_response_class` to `HttpEventInterface` for customizable response types. - Introduced `add_api_route_options` property for consistent route configuration. - Refined OpenAPI tag processing in `http_plugin_integration`. - Simplified router inclusion logic in `http_plugin_integration`. - Minor improvements to middleware and utility functions.
… plugin - Introduced `SpaceStateResponse` for refined API response models. - Added `Database Docs` plugin for generating OpenAPI documentation of database models. - Simplified type annotations and removed redundant `id` fields in sensor models. - Enhanced datetime fields with `examples` for better OpenAPI documentation.
- Merged `API Docs` and `Database Docs` plugins under a unified `docs` module for improved maintainability. - Added caching for database schema OpenAPI generation to enhance performance. - Updated OpenAPI schemas to include `x-logo` and additional metadata for customization. - Removed redundant fields and improved type annotations in `UILog` models.
…ations - Improved clarity of field descriptions across `SpaceStateHistory`, `SensorLog`, `SensorUnit`, `UILog`, and related models. - Added OpenAPI examples and configuration schemas to improve documentation. - Updated database docs with external links and schema adjustments.
Closed
- Updated API and database docs plugins to construct `externalDocs.url` dynamically with `fastapi_app.root_path.rstrip('/')`.
…nd `/database/openapi.json` endpoints from the logging.
…hanced documentation - Added detailed docstrings to `SpaceState`, `SpaceStateHistory`, `SensorLog`, and related models. - Integrated Jinja2 templating for improved HTML rendering in database schema documentation. - Updated dependencies to include `Jinja2` and `MarkupSafe`.
- Renamed `database_schema.html` to `database_collection_schema.html`. - Added `altText` and `href` fields to `x-logo` metadata. - Improved external links in OpenAPI documentation for database schema.
- Added `exc_info` to error logging in database initialization for better debugging. - Added unique index to SensorUnits.device
- Introduced `custom_database_redoc.html` for a fully customized Redoc interface. - Added additional metadata (`x-indexes`, `x-isDatabaseModel`, `x-collectionName`) to OpenAPI schemas for database models. - Implemented Jinja2 templating for flexible customization of database documentation. - Improved tag generation and grouping in OpenAPI schema for better organization. - Refactored redundant code and enriched metadata in database schema generation logic.
Contributor
There was a problem hiding this comment.
Pull Request Overview
This PR introduces database documentation via ReDoc at /database/docs, reorganizes the documentation plugin structure, and adds various enhancements to models and configuration. The changes primarily focus on making database schemas viewable through a web interface backed by OpenAPI specifications.
Key Changes
- Added
/database/docsendpoint using ReDoc to display all DB models and their fields with examples - Reorganized the docs plugin by moving API docs override into a new unified
docsplugin structure alongside database docs - Enhanced database models with improved documentation, field descriptions, and examples for better schema visibility
Reviewed Changes
Copilot reviewed 18 out of 19 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| src/smib/utilities/beanie_.py | New utility module for extracting index information from Beanie models |
| src/smib/utilities/init.py | Reorganized imports (removed unused, reordered existing) |
| src/smib/plugins/integrations/http_plugin_integration.py | Simplified tag merging logic and router inclusion |
| src/smib/events/middlewares/http_middleware.py | Fixed variable reference and added database docs paths to logging exclusions |
| src/smib/events/interfaces/http/http_web_event_interface.py | Added HTMLResponse as default for web interface |
| src/smib/events/interfaces/http/init.py | Added configurable default response class and new route options property |
| src/smib/db/manager.py | Enhanced error logging with exception info |
| src/plugins/space/spacestate/models.py | Refactored models with base classes, added documentation and improved field descriptions |
| src/plugins/space/spacestate/listeners/http.py | Updated response model to avoid exposing internal Document fields |
| src/plugins/space/smibhid/ui/models.py | Added field descriptions, documentation strings, and removed excluded ID field |
| src/plugins/space/smibhid/sensor/models.py | Enhanced with descriptions, examples, documentation, and improved index configuration |
| src/plugins/core/docs/templates/database_collection_schema.html | Template for rendering database collection schemas in ReDoc |
| src/plugins/core/docs/templates/custom_database_redoc.html | Custom ReDoc HTML template with JavaScript for index badge rendering |
| src/plugins/core/docs/templates/_redoc_base.html | Base ReDoc HTML template |
| src/plugins/core/docs/db_docs.py | New module implementing database documentation generation |
| src/plugins/core/docs/api_docs.py | Refactored API docs with logo/external docs and moved shared constants |
| src/plugins/core/docs/init.py | New plugin entry point coordinating API and database docs |
| pyproject.toml | Added jinja2 dependency for template rendering |
Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.
- Enabled `allow_index_dropping=True` during Beanie initialization for controlled schema updates. - Renamed `filter` parameter to `filter_` to avoid shadowing built-in names.
# Conflicts: # pyproject.toml # src/smib/events/interfaces/http/__init__.py
- Documented `/api/docs`, `/api/redoc`, and `/database/docs` in the README, providing details on their purpose and features. - Introduced a new "Documentation" section for better structure and clarity.
- Replaced direct JSON handling with SpaceStateResponse model for WebSocket state interactions. - Enhanced initial state retrieval and client updates with proper data transformations and logging.
- Improved support for `Settings.indexes` in Beanie models, including handling of single strings, `IndexModel`, and tuple formats.
- Change timestamp example from int to datetime object in SensorLog model - Add received_timestamp to SensorLog example for consistency - Add created_at and updated_at to LatestSensorData example - Ensures examples match actual model field types
sjefferson99
approved these changes
Oct 21, 2025
Member
sjefferson99
left a comment
There was a problem hiding this comment.
Container builds and docs show up as expected.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
/database/docsurl, using ReDoc. This shows all the DB models and their fields along with an example./api/docsoverride plugin into a newdocsplugin alongside the/database/docs.