[Bug]: REST API Documentation Page Hangs and Shows Resolver Errors

[movchan74]

Steps to reproduce

When accessing the run endpoints in the API reference documentation, the page takes an unusually long time to load and, upon scrolling, displays a resolver error related to the JSON schema.

1. Navigate to the REST API Documentation.
2. Click on the /api/runs/list endpoint.
3. Wait for the page to load (it eventually loads, but very slowly).
4. Scroll up on the page.
5. Notice the error messages like this:
   Resolver error at responses.200.content.application/json.schema.items.$ref

Actual behaviour

• The page hangs and loads very slowly.
• Upon scrolling up, the following error messages appear:
  Resolver error at responses.200.content.application/json.schema.items.$ref

Expected behaviour

• The documentation should load promptly.
• The endpoint details should render correctly without any errors.

dstack version

Server logs

Additional information

Browser: Firefox 136

[r4victor]

This appears to be caused by the schema substitution of ResourcesSpec with its less restrictive equivalent:

dstack/src/dstack/_internal/core/models/resources.py

Lines 253 to 261 in 775e656

	class ResourcesSpec(CoreModel):
	class Config:
	@staticmethod
	def schema_extra(schema: Dict[str, Any]):
	schema.clear()
	# replace strict schema with a more permissive one
	ref_template = "#/definitions/ResourcesSpecRequest/definitions/{model}"
	for field, value in ResourcesSpecSchema.schema(ref_template=ref_template).items():
	schema[field] = value

No errors if I remove the schema substitution. Perhaps, we should drop it since this substitution pattern is not used with other models anyway.

[r4victor]

On the other hand, dropping it is undesirable since then specifying something like gpu: 2.. would be highlighted as an error.

[r4victor]

I think I found the solution. We can manually add additional allowed types without defining duplicating models like so:

class ResourcesSpec(CoreModel):
    class Config:
        @staticmethod
        def schema_extra(schema: Dict[str, Any]):
            ref = schema['properties']['cpu'].pop("allOf")[0]
            schema['properties']['cpu']["anyOf"] = [
                ref,
                {'type': 'integer'},
                {'type': 'string'},
            ]

This does not lead to any errors.