RFC 9512 declaresapplication/yaml as the official content-type for YAML-based types. One thing I observed is that this MIME type is fairly new and most browsers still don't know how to render it inline and will fallback to downloading the YAML file to disk.

To get around this, we could use thetext/plain+yaml content type to force inline rendering while still being in compliance with the MIME type spec for YAML.

Side note: ThisRFC is in draft which defines an officialapplication/openapi content type that we might consider using in the future.

Based on my limited knowledge of MIME types,application/yaml seems more correct since it is primarily for programmatic consumption, but I can definitely imagine people asking fortext+yaml as a convenience. I see one of the RFC authors was from Mozilla, so hopefully built-in support isn't too far off?

Do any of these tests validate it is actually YAML? They check the content type and that a OpenAPI parser can parse the content, but if you replaced the writer implementation in the YAML block with the JSON one would they still pass?

Yep, it would still pass if the writer used was a JSON one. Since JSON is valid YAML, if we wanted to verify that the emitted content was actually YAML we'd have to perhaps do some string-based check to see if it contained the correct starting characters compared to a JSON output?

TIL JSON is YML, but that still feels wrong to me that the tests wouldn't detect the content not being the requested format.

Based on my limited knowledge of MIME types,application/yaml seems more correct since it is primarily for programmatic consumption, but I can definitely imagine people asking fortext+yaml as a convenience. I see one of the RFC authors was from Mozilla, so hopefully built-in support isn't too far off?

I assumeOpenApiYamlWriter does smart things to guard against, e.g., the Norway Problem?

OpenAPI recommends YAML 1.2 of the spec, which prohibits non-boolean string literals from being interpreted as booleans, AFAIK.

The serialization itself seems to emit it as a string correctly. For example:

[JsonConverter(typeof(JsonStringEnumConverter<Choices>))]public enum Choices{    Yes,    No}

becomes

schemas:    Choices:      enum:        - Yes        - No

Are people going to be surprised whenopenapi.toml returns JSON, rather than failing?

Maybe give more control for the user, passing all values in params, and give some magic extension .json or .yaml in the end of path if exists or not or wrong will be removed and set the right extension, for content type / mime type pass in the last param like mimeType: | default value like pattern: "openapi/v1" format: JSON mimeType: "application/json" ( 0-0)/

Are people going to be surprised when openapi.toml returns JSON, rather than failing?

Depends on user expectation and the type of experience that we want to provide. TOML isn't a supported OpenAPI document format so we could decide to throw if we encounter an extensionand it's not associated with the supported set of formats.

• Route with extension ending in.yaml oryml produces an OpenAPI document in YAML format.
• Route with extension ending in.json produces an OpenAPI document in JSON format.
• Route with extension not ending in any of the above produces an error.
• Route with no extension produces an OpenAPI document in JSON format.

With this behavior,#3 would be a breaking change between .NET 9 and .NET 10 but I think we can live with it.

Maybe give more control for the user, passing all values in params, and give some magic extension .json or .yaml in the end of path if exists or not or wrong will be removed and set the right extension, for content type / mime type pass in the last param like mimeType: | default value like pattern: "openapi/v1" format: JSON mimeType: "application/json" ( 0-0)/

Yeah, I considered this option as well but opted to be more conservative in the amount of new API that was introduced. It also feels that given there are only two formats supported currently, we might want to support a simpler API for this.

I've opted to avoid the breaking change for now. We've got runaway to revisit this if needed.