agentic-community / agentic-community/mcp-gateway-registry

Add auto-generated Configuration Reference endpoint and UI tab

未关闭
#536 0 条评论 0 个 reaction 已指派 1 人 已被 @aarora79 认领 在 GitHub 查看
api enhancement
主要语言
Python
星标
912
派生
234
平均合并
1 天 11 小时
30 天内合并 PR
62

描述

## Problem Statement

The registry has 80+ configuration parameters across 11 groups (auth, storage, embeddings, security scanning, etc.). Today, configuration documentation is maintained in a static `docs/configuration.md` file (700+ lines) that must be manually kept in sync with the Pydantic `Settings` class in `registry/core/config.py`. When new settings are added, the documentation inevitably falls behind.

The existing `/api/config/full` endpoint shows current **values** of config parameters but provides no documentation about what each parameter does, what values are valid, or what the environment variable name is.

## Proposed Solution

Add a `/api/config/docs` endpoint that auto-generates configuration parameter documentation directly from the Pydantic `Settings` model -- similar to how FastAPI auto-generates `/docs` from route definitions.

This requires:
1. Adding `Field(description=...)` to all settings fields in `config.py`
2. Creating a new `/api/config/docs` endpoint that returns grouped, documented config parameters with types, defaults, env var names, and descriptions
3. Adding a "Config Reference" tab in the existing ConfigPanel UI component

## User Stories

- As an operator, I want to see what configuration parameters are available and what they do without reading source code or a separate docs file
- As a developer, I want config documentation that is always in sync with the code so I never deploy with outdated docs
- As an admin viewing the Settings page, I want a "Config Reference" tab alongside the "Current Values" view that documents all available parameters

## Acceptance Criteria

- [ ] All Settings fields in `config.py` have `Field(description=...)` annotations
- [ ] `GET /api/config/docs` returns grouped config parameter documentation (no auth required for read-only schema info)
- [ ] Each parameter in the response includes: name, env_var, type, default, description, group, is_sensitive, constraints (min/max/options)
- [ ] Frontend ConfigPanel has a "Config Reference" tab showing the documentation
- [ ] Config Reference tab supports search/filter by env var name, description, and label
- [ ] Sensitive fields are documented but their defaults are not exposed
- [ ] The endpoint works without any external dependencies (no database needed)
- [ ] Existing `/api/config/full` and `/api/config/export` endpoints are unchanged
- [ ] A regression test verifies all Settings fields have non-empty descriptions

## Technical Approach

### Backend
- Add `Field(description=...)` to all 80+ Settings fields in `registry/core/config.py`
- Add `GET /api/config/docs` endpoint to `registry/api/config_routes.py` that introspects `Settings.model_fields` to extract type, description, default, and constraints
- Reuse existing `CONFIG_GROUPS` dict for grouping (consistent with `/api/config/full`)
- Cache the docs response at module level (schema is static at runtime, build once)
- No authentication required (returns schema metadata only, no runtime values)
- Handle both `typing.Union` and Python 3.10+ `types.UnionType` for type introspection

### Frontend
- New `ConfigReferencePanel.tsx` component that fetches from `/api/config/docs`
- Tab switcher in existing `ConfigPanel.tsx`: "Current Values" | "Config Reference"
- Reuse existing search and collapsible group patterns
- Show env var name, type badge, default value, description, and constraints for each parameter
- Hide export dropdown on "Config Reference" tab (read-only documentation)

### Response Shape
```json
{
"groups": [
{
"id": "auth",
"title": "Authentication",
"order": 3,
"fields": [
{
"name": "auth_provider",
"env_var": "AUTH_PROVIDER",
"label": "Auth Provider",
"type": "string",
"default": "cognito",
"description": "Authentication provider: cognito, keycloak, entra, or github",
"is_sensitive": false,
"is_required": false,
"constraints": {}
}
]
}
],
"total_fields": 76,
"total_groups": 11
}
```

## Out of Scope

- Config editing/updating via the UI (read-only reference only)
- Auto-generating `docs/configuration.md` from code (future enhancement)
- Config validation before applying (future enhancement)
- Comparing config between environments

## Design Documents

Full design documents (LLD and expert review) available in `.scratchpad/config-docs/`.

贡献指南

打开贡献指南

评估

这个 Issue 还没有评估数据。

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。