E3SM-Project / E3SM-Project/simboard

[Docs]: Role-Based OpenAPI Documentation Visibility

Open
#106 0 comments 0 reactions 0 assignees View on GitHub
type: doc type: enhancement
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.