Parameter examples incorrectly emitted at the Parameter Object level for OpenAPI 3.0

[mdaneri]

Description

When generating an OpenAPI 3.0 document using Microsoft.OpenApi
3.1.1, assigning an example via examples for a parameter
component causes the library to emit examples at the Parameter
Object level, producing an invalid OpenAPI 3.0 document.

Swagger Editor reports errors such as:

If content is present, the following fields are not allowed:
style, explode, allowReserved, example, examples

According to OpenAPI 3.0.3: - A Parameter Object must contain
either schema (optionally with
example/examples/style/explode/allowReserved) or a
content map. - example / examples must not be added at the
Parameter Object level when content is present. - If examples are used
with content, they must appear under:
parameter.content.<mediaType>.examples.<exampleName>.$ref

Minimal C# reproduction

using Microsoft.OpenApi;
using System.Text.Json.Nodes;

var doc = new OpenApiDocument
{
    Info = new OpenApiInfo
    {
        Title = "Sample API",
        Version = "1.0.0"
    },

    Components = new OpenApiComponents
    {
        Schemas = new Dictionary<string, IOpenApiSchema>()
    }
};

var schema = new OpenApiSchema
{
    Type = JsonSchemaType.Object,
    Properties = new Dictionary<string, IOpenApiSchema>
    {
        ["id"] = new OpenApiSchema { Type = JsonSchemaType.String }
    }
};

var parameter = new OpenApiParameter
{
    Name = "productItems",
    In = ParameterLocation.Header,
    Required = true,
    Description = "Product item in header",
    Content = new Dictionary<string, IOpenApiMediaType>
    {
        ["application/json"] = new OpenApiMediaType
        {
            Schema =  schema
        }
    },
    Examples = new Dictionary<string, IOpenApiExample>
    {
        ["example1"] = new OpenApiExample
        {
            Value =  JsonNode.Parse(@"{ ""id"": ""123"" }")
        }
    }
};

doc.Components.Parameters = new Dictionary<string, IOpenApiParameter>
{
    ["ProductHeader"] = parameter
};


using var writerV2 = new StringWriter();
doc.SerializeAsV2(new OpenApiJsonWriter(writerV2));
string jsonV2 = writerV2.ToString();

File.WriteAllText("openapi_generated-2.0.json", jsonV2);

using var writerV3 = new StringWriter();
doc.SerializeAsV3(new OpenApiJsonWriter(writerV3));
string jsonV3 = writerV3.ToString();

File.WriteAllText("openapi_generated-3.0.json", jsonV3);


using var writerV31 = new StringWriter();
doc.SerializeAsV31(new OpenApiJsonWriter(writerV31));
string jsonV31 = writerV31.ToString();

File.WriteAllText("openapi_generated-3.1.json", jsonV31);


using var writerV32 = new StringWriter();
doc.SerializeAsV32(new OpenApiJsonWriter(writerV32));
string jsonV32 = writerV32.ToString();

File.WriteAllText("openapi_generated-3.2.json", jsonV32);

System.Console.WriteLine("Generated OpenAPI JSON saved to openapi_generated-2.0.json, openapi_generated-3.0.json, openapi_generated-3.1.json, and openapi_generated-3.2.json");

// The generated OpenAPI 3.0 document contains `examples`
// at the Parameter Object level, which is invalid when `content` is present.

// to run:
// dotnet new console -n OpenApiParameterExamplesBugDemo
// cd OpenApiParameterExamplesBugDemo
// dotnet add package Microsoft.OpenApi --version 3.1.1
// dotnet run

Steps to reproduce

1. Run the code above
2. Validate the generated document as OpenAPI 3.0 in Swagger Editor
3. Observe a validation error regarding examples and content

Expected behavior

When emitting OpenAPI 3.0: - Do not write examples at the
Parameter Object level if content is present. - If examples are
provided, they should be placed under:
parameter.content["application/json"].examples["ProductItemExample"].$ref

Actual behavior

The library emits:

"examples": {
  "application/json": {
    "$ref": "#/components/examples/ProductItemExample"
  }
}

The library emits examples at the Parameter Object level, producing an invalid OpenAPI 3.0 document, despite remaining valid for OpenAPI 3.1 and 3.2.

When the document is serialized as Swagger 2.0, the generator also omits the mandatory type field for all non-body parameters (header, query, path, formData).
This results in an invalid Swagger 2.0 definition, as the spec requires a primitive type whenever in is not body.

Affected tooling

• Swagger Editor
• API gateways performing strict OpenAPI 3.0 validation
• Any downstream tooling consuming serialized 3.0 documents

---

Microsoft.OpenApi version: 3.1.1
Target OpenAPI serialization: 3.0

[baywet]

Hi @mdaneri
Thank you for using the SDK and for reaching out.

I think swagger editor is enforcing an "oversight from the specification" here. I'm not sure why you wouldn't be able to use the content and example fields in combination? (i.e. what would be the explicit limitation?)

Also, while the example field is listed in the schema group in v3, it's moved to the common fields in v3.2.0. Which would support the assertion of "it's perfectly fine to use example in combination with content for parameter objects".

I suggest you open a new issue on swagger editor to get an answer from this group.

Let us know if you have any additional comments or questions.

[mdaneri]

Hi @baywet
Just to clarify — the limitation is explicit in OpenAPI 3.0.3:

A parameter object must contain either schema or content, but not both.

Because of that:

• example / examples are not allowed at the Parameter Object level when content is used

• Instead, examples must be nested under the media type, like:

  parameter.content["application/json"].examples["ExampleName"].$ref
  

So this isn’t Swagger Editor being strict — it’s correctly flagging a doc that’s invalid for 3.0.3, because the library emits examples at the wrong level when serializing to 3.0.

And yep — 3.2 allows example + content together, but that doesn’t change the older 3.0.3 rule. The generator just needs to be aware of the target spec version.

Also, I confirmed that the Swagger 2.0 output is invalid too, since it’s missing the required primitive type for in: header parameters.

I’ll open a new issue focusing on version-aware parameter serialization and the missing type in Swagger 2.0.

Thanks again — really appreciate you taking the time to help!

[baywet]

Right, what I was trying to say earlier is that even though the example field is under the schema set of fields, it really never should have been there in the first place. But maybe it's worth opening an issue on the OpenAPI specification repository to get some clarity about this?