[Question]: RequestBody Parameter Ordering

[ramneettung-msft]

What are you wanting to achieve?

Hi,

We were generating our swagger using a different library before on netframework, and have recently migrated to netcore and started to use swashbuckle. We notice that the request body is added to the end of the parameter list and there doesn't seem to be a way to adjust where in the parameter list it appears. This is causing an issue for us since we have previously generated swaggers with the request body as the 2nd parameter in the list and now it appears in a different spot. I believe this appears as a breaking change in our swagger.

Can you please help and point if I am missing anywhere that I can adjust this. Or do we need a feature enhancement for something like this?

Thanks,
Ramneet

What code or approach do you have so far?

• Filters
• Preserialization filters

Additional context

I was thinking maybe of putting my own middleware that executes after the SwaggerMiddleware that would adjust the JSON directly before returning it but i believe that the current Middleware just returns a response right away.

[martincostello]

Assuming I'm understanding what you're describing correctly, the ordering in the serialized document is dictated by the serialization internals of the OpenApiOperation class type in Microsoft.OpenApi.

If that's not what you're referring to, please clarify exactly where you're observing the ordering of parameters being different and in what version of Swashbuckle.AspNetCore.

[ramneettung-msft]

Yes that is correct, I am referring to that. Is there any way to adjust the ordering so that I can put the request body parameter earlier in a list, right now it always defaults to the end and there is no way to adjust that.

[martincostello]

Not really - the way the document is written out is an implementation detail in Microsoft.OpenApi. You would need to change the behaviour of OpenApiOperation to change the order of operations.

Alternatively, you could buffer the response, then re-read the JSON in a middleware and update the document and re-write it to the response, then it should be serialized in whatever arbitrary order you want.

[ramneettung-msft]

So I did actually think of that for the middleware part, but I think SwaggerMiddleware:

https://github.com/domaindrivendev/Swashbuckle.AspNetCore/blob/master/src/Swashbuckle.AspNetCore.Swagger/SwaggerMiddleware.cs

Does not call the next middleware in the chain, it just processes it and returns. Should we allow it to call the next middleware in the pipeline by adding:

public async Task Invoke(HttpContext httpContext, ISwaggerProvider swaggerProvider)
    {
        if (!RequestingSwaggerDocument(httpContext.Request, out string documentName, out string extension))
        {
            await _next(httpContext);
            return;
        }

        try
        {
            var basePath = httpContext.Request.PathBase.HasValue
                ? httpContext.Request.PathBase.Value
                : null;

            OpenApiDocument swagger;
            var asyncSwaggerProvider = httpContext.RequestServices.GetService<IAsyncSwaggerProvider>();

            if (asyncSwaggerProvider is not null)
            {
                swagger = await asyncSwaggerProvider.GetSwaggerAsync(
                    documentName: documentName,
                    host: null,
                    basePath: basePath);
            }
            else
            {
                swagger = swaggerProvider.GetSwagger(
                    documentName: documentName,
                    host: null,
                    basePath: basePath);
            }

            // One last opportunity to modify the Swagger Document - this time with request context
            foreach (var filter in _options.PreSerializeFilters)
            {
                filter(swagger, httpContext.Request);
            }

            if (extension is ".yaml" or ".yml")
            {
                await RespondWithSwaggerYaml(httpContext.Response, swagger);
            }
            else
            {
                await RespondWithSwaggerJson(httpContext.Response, swagger);
            }
        }
        catch (UnknownSwaggerDocument)
        {
            httpContext.Response.StatusCode = 404;
        }

        // TODO: Cal the next middleware in the pipeline
        await _next(httpContext);

    }

[martincostello]

Ah, I'd forgotten about that.

In that case we would invert the condition on line 21 and replace the code block with the try-catch block, then just call await _next(httpContext) always.

That seems a reasonable change provided it doesn't cause any intended behaviour for later middlewares in a common ASP.NET Core application that would try to process things that they shouldn't when it's a Swagger document.

[ramneettung-msft]

Microsoft.AspNetCore.Builder.SwaggerBuilderExtensions
Microsoft.Extensions.DependencyInjection.SwaggerOptionsExtensions
Microsoft.Extensions.DependencyInjection.SwaggerServiceCollectionExtensions
static Microsoft.AspNetCore.Builder.SwaggerBuilderExtensions.MapSwagger(this Microsoft.AspNetCore.Routing.IEndpointRouteBuilder endpoints, string pattern = "/swagger/{documentName}/swagger.{extension:regex(^(json|ya?ml)$)}", System.Action<Swashbuckle.AspNetCore.Swagger.SwaggerEndpointOptions> setupAction = null) -> Microsoft.AspNetCore.Builder.IEndpointConventionBuilder
static Microsoft.AspNetCore.Builder.SwaggerBuilderExtensions.UseSwagger(this Microsoft.AspNetCore.Builder.IApplicationBuilder app, Swashbuckle.AspNetCore.Swagger.SwaggerOptions options) -> Microsoft.AspNetCore.Builder.IApplicationBuilder
static Microsoft.AspNetCore.Builder.SwaggerBuilderExtensions.UseSwagger(this Microsoft.AspNetCore.Builder.IApplicationBuilder app, System.Action<Swashbuckle.AspNetCore.Swagger.SwaggerOptions> setupAction = null) -> Microsoft.AspNetCore.Builder.IApplicationBuilder
static Microsoft.Extensions.DependencyInjection.SwaggerOptionsExtensions.SetCustomDocumentSerializer<TDocumentSerializer>(this Swashbuckle.AspNetCore.Swagger.SwaggerOptions swaggerOptions, params object[] constructorParameters) -> void
static Microsoft.Extensions.DependencyInjection.SwaggerServiceCollectionExtensions.ConfigureSwagger(this Microsoft.Extensions.DependencyInjection.IServiceCollection services, System.Action<Swashbuckle.AspNetCore.Swagger.SwaggerOptions> setupAction) -> void
Swashbuckle.AspNetCore.Swagger.IAsyncSwaggerProvider
Swashbuckle.AspNetCore.Swagger.IAsyncSwaggerProvider.GetSwaggerAsync(string documentName, string host = null, string basePath = null) -> System.Threading.Tasks.Task<Microsoft.OpenApi.OpenApiDocument>
Swashbuckle.AspNetCore.Swagger.ISwaggerDocumentMetadataProvider
Swashbuckle.AspNetCore.Swagger.ISwaggerDocumentMetadataProvider.GetDocumentNames() -> System.Collections.Generic.IList<string>
Swashbuckle.AspNetCore.Swagger.ISwaggerDocumentSerializer
Swashbuckle.AspNetCore.Swagger.ISwaggerDocumentSerializer.SerializeDocument(Microsoft.OpenApi.OpenApiDocument document, Microsoft.OpenApi.IOpenApiWriter writer, Microsoft.OpenApi.OpenApiSpecVersion specVersion) -> void
Swashbuckle.AspNetCore.Swagger.ISwaggerProvider
Swashbuckle.AspNetCore.Swagger.ISwaggerProvider.GetSwagger(string documentName, string host = null, string basePath = null) -> Microsoft.OpenApi.OpenApiDocument
Swashbuckle.AspNetCore.Swagger.SwaggerEndpointOptions
Swashbuckle.AspNetCore.Swagger.SwaggerEndpointOptions.OpenApiVersion.get -> Microsoft.OpenApi.OpenApiSpecVersion
Swashbuckle.AspNetCore.Swagger.SwaggerEndpointOptions.OpenApiVersion.set -> void
Swashbuckle.AspNetCore.Swagger.SwaggerEndpointOptions.PreSerializeFilters.get -> System.Collections.Generic.List<System.Action<Microsoft.OpenApi.OpenApiDocument, Microsoft.AspNetCore.Http.HttpRequest>>
Swashbuckle.AspNetCore.Swagger.SwaggerEndpointOptions.SwaggerEndpointOptions() -> void
Swashbuckle.AspNetCore.Swagger.SwaggerOptions
Swashbuckle.AspNetCore.Swagger.SwaggerOptions.CustomDocumentSerializer.get -> Swashbuckle.AspNetCore.Swagger.ISwaggerDocumentSerializer
Swashbuckle.AspNetCore.Swagger.SwaggerOptions.CustomDocumentSerializer.set -> void
Swashbuckle.AspNetCore.Swagger.SwaggerOptions.ExtendedMiddleware.get -> bool
Swashbuckle.AspNetCore.Swagger.SwaggerOptions.ExtendedMiddleware.set -> void
Swashbuckle.AspNetCore.Swagger.SwaggerOptions.OpenApiVersion.get -> Microsoft.OpenApi.OpenApiSpecVersion
Swashbuckle.AspNetCore.Swagger.SwaggerOptions.OpenApiVersion.set -> void
Swashbuckle.AspNetCore.Swagger.SwaggerOptions.PreSerializeFilters.get -> System.Collections.Generic.List<System.Action<Microsoft.OpenApi.OpenApiDocument, Microsoft.AspNetCore.Http.HttpRequest>>
Swashbuckle.AspNetCore.Swagger.SwaggerOptions.RouteTemplate.get -> string
Swashbuckle.AspNetCore.Swagger.SwaggerOptions.RouteTemplate.set -> void
Swashbuckle.AspNetCore.Swagger.SwaggerOptions.SwaggerOptions() -> void
Swashbuckle.AspNetCore.Swagger.UnknownSwaggerDocument
Swashbuckle.AspNetCore.Swagger.UnknownSwaggerDocument.UnknownSwaggerDocument(string documentName, System.Collections.Generic.IEnumerable<string> knownDocuments) -> void

using Microsoft.AspNetCore.Http;
using Microsoft.OpenApi;

namespace Swashbuckle.AspNetCore.Swagger;

public class SwaggerOptions
{
    internal const string DefaultRouteTemplate = "/swagger/{documentName}/swagger.{extension:regex(^(json|ya?ml)$)}";

    public SwaggerOptions()
    {
        PreSerializeFilters = [];
        OpenApiVersion = OpenApiSpecVersion.OpenApi3_0;
    }

    /// <summary>
    /// Sets a value indicating whether to use extended middleware.
    /// </summary>
    public bool ExtendedMiddleware { get; set; } = false;

    /// <summary>
    /// Sets a custom route for the Swagger JSON/YAML endpoint(s). Must include the {documentName} parameter
    /// </summary>
    public string RouteTemplate { get; set; } = DefaultRouteTemplate;

    /// <summary>
    /// Gets or sets the OpenAPI (Swagger) document version to use.
    /// </summary>
    /// <remarks>
    /// The default value is <see cref="OpenApiSpecVersion.OpenApi3_0"/>.
    /// </remarks>
    public OpenApiSpecVersion OpenApiVersion { get; set; }

    /// <summary>
    /// Gets or sets an optional custom <see cref="ISwaggerDocumentSerializer"/> implementation to use to serialize Swagger documents.
    /// </summary>
    /// <remarks>For the CLI tool to be able to use this, this needs to be configured for use in the service collection of your application.</remarks>
    public ISwaggerDocumentSerializer CustomDocumentSerializer { get; set; }

    /// <summary>
    /// Actions that can be applied to an OpenApiDocument before it's serialized.
    /// Useful for setting metadata that's derived from the current request.
    /// </summary>
    public List<Action<OpenApiDocument, HttpRequest>> PreSerializeFilters { get; private set; }
}

using System.Globalization;
using System.Text;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Routing;
using Microsoft.AspNetCore.Routing.Patterns;
using Microsoft.AspNetCore.Routing.Template;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.OpenApi;

namespace Swashbuckle.AspNetCore.Swagger;

internal sealed class SwaggerMiddleware
{
    private static readonly Encoding UTF8WithoutBom = new UTF8Encoding(false);

    private readonly RequestDelegate _next;
    private readonly SwaggerOptions _options;
    private readonly TemplateMatcher _requestMatcher;
    private readonly TemplateBinder _templateBinder;

    public SwaggerMiddleware(
        RequestDelegate next,
        SwaggerOptions options)
    {
        _next = next;
        _options = options ?? new SwaggerOptions();
        _requestMatcher = new TemplateMatcher(TemplateParser.Parse(_options.RouteTemplate), []);
    }

    [ActivatorUtilitiesConstructor]
    public SwaggerMiddleware(
        RequestDelegate next,
        SwaggerOptions options,
        TemplateBinderFactory templateBinderFactory) : this(next, options)
    {
        _templateBinder = templateBinderFactory.Create(RoutePatternFactory.Parse(_options.RouteTemplate));
    }

    public async Task Invoke(HttpContext httpContext, ISwaggerProvider swaggerProvider)
    {
        var requestSwaggerDocument = RequestingSwaggerDocument(httpContext.Request, out string documentName, out string extension);

        if (requestSwaggerDocument)
        {
            try
            {
                var basePath = httpContext.Request.PathBase.HasValue
                    ? httpContext.Request.PathBase.Value
                    : null;

                OpenApiDocument swagger;
                var asyncSwaggerProvider = httpContext.RequestServices.GetService<IAsyncSwaggerProvider>();

                if (asyncSwaggerProvider is not null)
                {
                    swagger = await asyncSwaggerProvider.GetSwaggerAsync(
                        documentName: documentName,
                        host: null,
                        basePath: basePath);
                }
                else
                {
                    swagger = swaggerProvider.GetSwagger(
                        documentName: documentName,
                        host: null,
                        basePath: basePath);
                }

                // One last opportunity to modify the Swagger Document - this time with request context
                foreach (var filter in _options.PreSerializeFilters)
                {
                    filter(swagger, httpContext.Request);
                }

                if (extension is ".yaml" or ".yml")
                {
                    await RespondWithSwaggerYaml(httpContext.Response, swagger);
                }
                else
                {
                    await RespondWithSwaggerJson(httpContext.Response, swagger);
                }
            }
            catch (UnknownSwaggerDocument)
            {
                httpContext.Response.StatusCode = 404;
            }
        }

        if(_options.ExtendedMiddleware || !requestSwaggerDocument)
        {
            await _next(httpContext);
            return;
        }
    }

    private bool RequestingSwaggerDocument(HttpRequest request, out string documentName, out string extension)
    {
        documentName = null;
        extension = null;

        if (!HttpMethods.IsGet(request.Method))
        {
            return false;
        }

        var routeValues = new RouteValueDictionary();
        if (_requestMatcher.TryMatch(request.Path, routeValues))
        {
            if (_templateBinder != null && !_templateBinder.TryProcessConstraints(request.HttpContext, routeValues, out _, out _))
            {
                return false;
            }

            if (routeValues.TryGetValue("documentName", out var documentNameObject) && documentNameObject is string documentNameString)
            {
                documentName = documentNameString;
                if (routeValues.TryGetValue("extension", out var extensionObject))
                {
                    extension = $".{extensionObject}";
                }
                else
                {
                    extension = Path.GetExtension(request.Path.Value);
                }
                return true;
            }
        }

        return false;
    }

    private async Task RespondWithSwaggerJson(HttpResponse response, OpenApiDocument swagger)
    {
        string json;

        using (var textWriter = new StringWriter(CultureInfo.InvariantCulture))
        {
            var openApiWriter = new OpenApiJsonWriter(textWriter);

            SerializeDocument(swagger, openApiWriter);

            json = textWriter.ToString();
        }

        response.StatusCode = 200;
        response.ContentType = "application/json;charset=utf-8";

        await response.WriteAsync(json, UTF8WithoutBom);
    }

    private async Task RespondWithSwaggerYaml(HttpResponse response, OpenApiDocument swagger)
    {
        string yaml;

        using (var textWriter = new StringWriter(CultureInfo.InvariantCulture))
        {
            var openApiWriter = new OpenApiYamlWriter(textWriter);

            SerializeDocument(swagger, openApiWriter);

            yaml = textWriter.ToString();
        }

        response.StatusCode = 200;
        response.ContentType = "text/yaml;charset=utf-8";

        await response.WriteAsync(yaml, UTF8WithoutBom);
    }

    private void SerializeDocument(
        OpenApiDocument document,
        IOpenApiWriter writer)
    {
        if (_options.CustomDocumentSerializer != null)
        {
            _options.CustomDocumentSerializer.SerializeDocument(document, writer, _options.OpenApiVersion);
        }
        else
        {
            document.SerializeAs(_options.OpenApiVersion, writer);
        }
    }
}

[ramneettung-msft]

Just an idea but we could add a flag in swagger options that would explicitly need you to opt-in for extending this functionality with middleware so we wouldn't break other's code. Anyways, let me know thanks!

[martincostello]

#3706 (comment) is quite a wall of text to see what the difference is.

Feel free to open a draft PR with a proposal and I'll take a look.

[github-actions]

This issue is stale because it has been open for 60 days with no activity. It will be automatically closed in 14 days if no further updates are made.

[github-actions]

This issue was closed because it has been inactive for 14 days since being marked as stale.