Serve OpenAPI Schema as YAML

[lvlcn-t]

Issue

Currently quart-schema only has a /openapi.json route to serve the OpenAPI schema. This is not ideal for some use cases, such as when external tools require the schema to be served as a .yaml file.

Problem Description

To serve the OpenAPI schema as a yaml, the user has to either manually convert the served json to yaml, use a seperate library to do so, import the "private" function _build_openapi_schema and dump the dictionary to the yaml format and then serve an additional route to serve the yaml schema or completely build the schema from scratch. This is not ideal as it is not user friendly and requires additional work.

Solution Proposal

Add a new route /openapi.yaml that serves the OpenAPI schema under (openapi-path)/openapi.yaml. This would make it easier for users to serve the schema as a yaml. To do this you could use the _build_openapi_schema function mentioned above and dump the dictionary to yaml. This could look like this (simplified):

@hide
async def openapi_yaml(self) -> ResponseTypes:
    """openapi_yaml returns the openapi schema as a yaml string."""
    schema: dict[str, Any] = _build_openapi_schema(current_app, self)
    schema_yaml = yaml.dump(schema, indent=2)
    response = await make_response(schema_yaml)
    response.headers["Content-Type"] = "text/yaml"
    response.headers["Content-Disposition"] = "inline"
    return response

Additional Context

https://github.com/pgjones/quart-schema/blob/main/src/quart_schema/extension.py#L320 https://github.com/pgjones/quart-schema/blob/main/src/quart_schema/extension.py#L646

[pgjones]

I'm not sure this should be built in (it would require an extra dependency among other additions). The example you give is good as far as I'm concerned.

[lvlcn-t]

@pgjones I understand the concern about adding an extra dependency. I think if you feel strong about the extra dependency, then "publicly" exposing the _build_openapi_schema function would be a good alternative. This way users can build the schema themselves and serve it as they wish. I think this would be a good compromise between adding an extra dependency and making it easier for users to serve the schema as a yaml. What do you think?