Add support for media types

[marcuscfarias]

Hey, i would like to ask the support for media types, because I am uploading an image and the documentation doesnt follow the fluentvalidation rules. Check it below:

internal static class UploadProductImageConsts
{
    public const long MaxSizeBytes = 2 * 1024 * 1024;

    public static readonly string[] AllowedContentTypes = ["image/jpeg", "image/png"];
}

internal sealed class UploadProductImageRequestValidator : AbstractValidator<UploadProductImageRequest>
{
    public UploadProductImageRequestValidator()
    {
        RuleFor(x => x.File)
            .NotNull();

        RuleFor(x => x.File.Length)
            .GreaterThan(0)
            .LessThanOrEqualTo(UploadProductImageConsts.MaxSizeBytes)
            .When(x => x.File is not null);

        RuleFor(x => x.File.ContentType)
            .Must(UploadProductImageConsts.AllowedContentTypes.Contains)
            .When(x => x.File is not null);
    }
}

[avgalex]

Hi @marcuscfarias, thanks for the report! This is now implemented and shipped as a pre-release: 7.1.8-beta.1 (PR #218).

The root cause was that rules on nested IFormFile members (RuleFor(x => x.File.Length) / RuleFor(x => x.File.ContentType)) are named File.Length / File.ContentType, which never match the flat File schema property, and Must(...) carries no introspectable metadata — so nothing reached the OpenAPI document. There are now dedicated, File-level rules that both enforce at runtime and drive the OpenAPI output:

using MicroElements.OpenApi.FluentValidation.FileUpload;

RuleFor(x => x.File)
    .NotNull()
    .FileContentType("image/jpeg", "image/png")   // allowed media types
    .MaxFileSize(2 * 1024 * 1024);                // 2 MB

Also available: .MinFileSize(long) and .FileSizeBetween(long, long).

What you get in the generated document:

multipart/form-data:
  schema:
    properties:
      File:
        type: string
        format: binary
        description: "Allowed content types: image/jpeg, image/png. Maximum file size: 2097152 bytes."
  encoding:
    File:
      contentType: "image/jpeg, image/png"

Backend	content type + size in description	encoding.contentType
Swashbuckle	✅	✅ (net8/9 = OpenAPI 3.0; net10 = OpenAPI 3.1)
NSwag	✅	✅ (serialized as encodingType — a known NSwag limitation)
Microsoft.AspNetCore.OpenApi	✅	❌ not emitted

Notes:

• File size has no standard OpenAPI byte keyword, so it is surfaced in description only (enforcement stays server-side via FluentValidation).

Feedback welcome on the API shape before it goes stable.

[marcuscfarias]

Should I add something more in the Scalar config? Because isn't showing in the interface

[avgalex]

Scalar just renders whatever is in the generated OpenAPI document, so this isn't a Scalar-config thing — the constraint has to be present in /openapi/v1.json first. Two questions to narrow it down:

1. Are you using the new .FileContentType(...) rule, or still the original Must(...)?

The original pattern is exactly the one that does not work (and what this issue is about):

RuleFor(x => x.File.ContentType).Must(AllowedContentTypes.Contains); // silently ignored

FluentValidation names that rule File.ContentType, which never matches the flat File schema property, and Must(...) exposes no metadata — so nothing reaches the document. The fix is a dedicated rule applied on x.File directly:

RuleFor(x => x.File)
    .NotNull()
    .FileContentType("image/jpeg", "image/png")
    .MaxFileSize(2 * 1024 * 1024);

Note: the fix currently lives in the 7.1.8-beta.1 pre-release / the feature/issue-216-media-types branch — it is not on NuGet yet, so make sure you're building against that and not 7.1.7.

If you can, please paste the requestBody / file property from your generated /openapi/v1.json — that instantly shows whether the constraint is reaching the document.

2. Would you like me to add the structured encoding.contentType for the Microsoft.AspNetCore.OpenApi backend (the one Scalar uses)?

On that backend the allowed types + size are currently written to the file field's description (and on .NET 10 they land on the shared IFormFile component, which some UIs don't surface in the form-field row). We do not yet emit the machine-readable encoding.contentType there — that's the field a UI like Scalar would use to show an "accepted content types" hint.

It's feasible to add on both .NET 9 and .NET 10. If that's what you need for Scalar, say the word and I'll include it in the next beta.

[marcuscfarias]

1. About the question 1: Yes, I am going to send what scalar had generated below.

internal sealed class UploadProductImageRequestValidator : AbstractValidator<UploadProductImageRequest>
{
    public UploadProductImageRequestValidator()
    {
        RuleFor(x => x.File)
            .NotNull()
            .FileContentType("image/jpeg", "image/png")
            .MaxFileSize(2 * 1024 * 1024);
    }
}

"post": {
        "tags": [
          "Products"
        ],
        "description": "Uploads or replaces the product's image.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          }
        ],
        "requestBody": {
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "File": {
                    "$ref": "#/components/schemas/IFormFile"
                  }
                }
              }
            }
          },
          "required": true
        },
        "responses": {
          "204": {
            "description": "No Content"
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationProblemDetails"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationProblemDetails"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationProblemDetails"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      },

2. About the question 2: Actually, I don't know how its rendered under the hood, but I would like that my validator configs show in the scalar doc, not only the required. If u think its going to solve the problem, its up to you.

[avgalex]

Thanks @marcuscfarias — confirmed it's not a wiring issue (you're using the new API correctly), and your dump shows exactly the .NET 10 shape where the file part is a $ref to a shared IFormFile component, whose description Scalar doesn't render in the form-field row.

So I implemented option 2: Microsoft.AspNetCore.OpenApi now emits the machine-readable encoding.contentType for the file part. Shipped in 7.1.8-beta.2. Your document will now also contain:

"multipart/form-data": {
  "schema": { "$ref": "#/components/schemas/UploadProductImageRequest" },
  "encoding": {
    "File": { "contentType": "image/jpeg, image/png" }
  }
}

This is the spec-defined place for allowed media types on a multipart part, and it's what Scalar/Swagger UI use to show an "accepted types" hint. (Verified it lands in /openapi/v1.json on both .NET 9 and .NET 10.)

Honest caveat: I can't headlessly test Scalar's exact rendering here — but encoding.contentType is now in the document, which is the prerequisite. Could you update to 7.1.8-beta.2 and check whether Scalar shows it? If it still doesn't surface, please paste the new requestBody from your /openapi/v1.json and a Scalar screenshot, and I'll dig further.