fix: Add OpenAPI request body schema to all POST routes for Swagger UI

[Asthenia0412]

All POST routes in the router use raw FastAPI Request objects to forward the body to the backend, so FastAPI cannot infer the request body schema automatically. This makes the Swagger "Try it out" feature unusable for these endpoints.

Add a shared _REQUEST_BODY_SCHEMA constant and attach it via openapi_extra on every POST route so that the Swagger doc page renders a request body editor and allows users to actually send requests through the UI.

Closes #667

FILL IN THE PR DESCRIPTION HERE

FIX #xxxx (link existing issues this PR will resolve)

BEFORE SUBMITTING, PLEASE READ THE CHECKLIST BELOW AND FILL IN THE DESCRIPTION ABOVE

---

• Make sure the code changes pass the pre-commit checks.
• Sign-off your commit by using -s when doing git commit
• Try to classify PRs for easy understanding of the type of changes, such as [Bugfix], [Feat], and [CI].

Detailed Checklist (Click to Expand)

Thank you for your contribution to production-stack! Before submitting the pull request, please ensure the PR meets the following criteria. This helps us maintain the code quality and improve the efficiency of the review process.

PR Title and Classification

Please try to classify PRs for easy understanding of the type of changes. The PR title is prefixed appropriately to indicate the type of change. Please use one of the following:

• [Bugfix] for bug fixes.
• [CI/Build] for build or continuous integration improvements.
• [Doc] for documentation fixes and improvements.
• [Feat] for new features in the cluster (e.g., autoscaling, disaggregated prefill, etc.).
• [Router] for changes to the vllm_router (e.g., routing algorithm, router observability, etc.).
• [Misc] for PRs that do not fit the above categories. Please use this sparingly.

Note: If the PR spans more than one category, please include all relevant prefixes.

Code Quality

The PR need to meet the following code quality standards:

• Pass all linter checks. Please use pre-commit to format your code. See README.md for installation.
• The code need to be well-documented to ensure future contributors can easily understand the code.
• Please include sufficient tests to ensure the change is stay correct and robust. This includes both unit tests and integration tests.

DCO and Signed-off-by

When contributing changes to this project, you must agree to the DCO. Commits must include a Signed-off-by: header which certifies agreement with the terms of the DCO.

Using -s with git commit will automatically add this header.

What to Expect for the Reviews

We aim to address all PRs in a timely manner. If no one reviews your PR within 5 days, please @-mention one of YuhanLiu11
, Shaoting-Feng or ApostaC.

[gemini-code-assist]

Code Review

This pull request introduces a generic OpenAPI request body schema (_REQUEST_BODY_SCHEMA) and applies it to several POST endpoints in main_router.py to enable the Swagger "Try it out" feature. The review feedback correctly points out that applying this generic JSON schema to all endpoints is problematic. Specifically, /v1/audio/transcriptions and /v1/images/edits expect multipart/form-data instead of JSON, and /sleep and /wake_up do not require a request body at all. It is recommended to remove the schema from these endpoints or use a more appropriate definition.

[gemini-code-assist]

The /v1/audio/transcriptions endpoint expects multipart/form-data (including a file upload and other form fields like model), but _REQUEST_BODY_SCHEMA defines the content type as application/json.

Using _REQUEST_BODY_SCHEMA here will cause Swagger UI to render a JSON input field instead of a file upload control, making the "Try it out" feature unusable for audio transcriptions.

Consider removing openapi_extra=_REQUEST_BODY_SCHEMA or defining a schema compatible with multipart/form-data.

Suggested change

	@main_router.post("/v1/audio/transcriptions", openapi_extra=_REQUEST_BODY_SCHEMA)
	@main_router.post("/v1/audio/transcriptions")

[gemini-code-assist]

The /sleep endpoint does not require a request body (it is typically triggered via query parameters like id). Using _REQUEST_BODY_SCHEMA here sets "required": True, which forces Swagger UI users to provide a JSON body to execute the request. This is confusing and unnecessary.

Consider removing openapi_extra=_REQUEST_BODY_SCHEMA for this endpoint, or defining a schema where "required" is set to False.

Suggested change

	@main_router.post("/sleep", openapi_extra=_REQUEST_BODY_SCHEMA)
	@main_router.post("/sleep")

[gemini-code-assist]

The /wake_up endpoint does not require a request body (it is typically triggered via query parameters like id). Using _REQUEST_BODY_SCHEMA here sets "required": True, which forces Swagger UI users to provide a JSON body to execute the request. This is confusing and unnecessary.

Consider removing openapi_extra=_REQUEST_BODY_SCHEMA for this endpoint, or defining a schema where "required" is set to False.

Suggested change

	@main_router.post("/wake_up", openapi_extra=_REQUEST_BODY_SCHEMA)
	@main_router.post("/wake_up")

[Asthenia0412]

Addressed the review feedback:

• Removed openapi_extra from /sleep and /wake_up (no request body needed)
• Changed /v1/audio/transcriptions and /v1/images/edits to use _FORM_BODY_SCHEMA (multipart/form-data) instead of application/json
• Added a _FORM_BODY_SCHEMA constant for multipart endpoints

All 18 POST routes are now correctly categorized: 14 JSON, 2 multipart/form-data, 2 with no body schema.