E3SM-Project / E3SM-Project/simboard
[Docs]: Role-Based OpenAPI Documentation Visibility
- Dominant language
- Python
- Stars
- 1
- Forks
- 2
- Avg merge
- 24m
- Merged PRs (30d)
- 15
Description
### Is your feature request related to a problem?
Admin-only endpoints (e.g., `/users`, `/tokens`) currently appear in the default OpenAPI schema and Swagger UI for all authenticated users. While route-level authorization prevents access, exposing these endpoints in public docs creates unnecessary visibility and potential confusion.
### Describe the solution you'd like
- [ ] Tag admin-only endpoints (e.g., `tags=["admin"]`)
- [ ] Disable default `docs_url` and `openapi_url`
- [ ] Implement custom `/openapi.json` generation
- [ ] Filter out `admin`-tagged endpoints (e.g., `/users`, `/tokens`) for non-admin users
- [ ] Serve `/docs` behind authentication
- [ ] Maintain route-level authorization enforcement
### Describe alternatives you've considered
- [ ] Using `include_in_schema=False` (too static; hides endpoints for admins as well)
- [ ] Maintaining separate admin documentation service (adds complexity)
### Additional context
This change affects documentation visibility only and does not modify endpoint authorization behavior.
Contributor guide
Assessment
This issue has not been assessed yet.