Swashbuckle.webapi: How to set paramType and required for a parameter?

[PeterZong]

We can use [FromUri] and [FromBody] to indicates if the paramType is Path or Body. Actually Swagger supports 5 paramType: "path", "query", "body", "header", "form". I know we can use IOperationFilter to change the paramType dynamically. But I am wondering if there is any better solutions - E.g.:
///

Same, how can we set if the parameter is required or optional?

Thanks.

[AnthonyNeace]

You can set a parameter as required by using the Required attribute from System.ComponentModel.DataAnnotations.

Example:

/// <summary>
/// Describes this object.
/// </summary>
[Required] 
public string Description { get; set; }

It will otherwise default to optional.

[domaindrivendev]

For the most part, Swashbuckle should honor the [FromUri] and [FromBody] attributes and set paramType accordingly. However, it relies on Web API's IApiExplorer for much of it's metadata and there is a known bug there that causes complex types marked with [FromBody] to be described incorrectly. I'll refer you to #70 for more information and a potential workaround.

Parameters should be marked required by default but If you want to mark it optional you can just make it optional in the method signature. E.g.

public ProductList GetProducts(string type = null)

Then for complex types, you can mark individual properties required via data annotations as pointed out by AnthonyNeace above

Cheers

[Stefan-Z-Camilleri]

Do note that this does not work currently, at least with dotnet core

Having a parameter like so:

Results in the following:

i.e. AspNet parses it correctly... but Swashbuckle on the other hand...

This can be patched of course using an IOperationFilter... yet it would be nice if it were fixed.

[heldersepu]

@Stefan-Z-Camilleri what you are reporting is not related to this issue, it is actually a duplicate of #1161 ...

Ant that specific issue makes it all the way to the OpenAPI-Specification:
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#fixed-fields-7

[Stefan-Z-Camilleri]

Thank you for the clarification @heldersepu

In that case, this makes sense and I wouldn't fix it either. A workaround is totally possible (and already done in my case) via an IOperationFilter, so nothing to do here.

[tomglenn]

Sorry to necro an old issue, but this is still the case in dot net core.
@Stefan-Z-Camilleri you mentioned it can be worked around with an IOperationFilter. Are you able to share how this can be done?

[Stefan-Z-Camilleri]

Hey @tomglenn ... sadly I have moved on to other pastures since this and no longer have access to this code... and in fact, am currently not even touching the .NET world.

That said, IIRC, I had used an IOperationFilter to intercept the call and modify the data before it actually gets to the rendering pipeline.

My suggestion for you is to create a basic IOperationFilter, register it and then place a breakpoint there to investigate what the object tree looks like at that point and modify it accordingly.

[tomglenn]

Hi @Stefan-Z-Camilleri, thanks for such a quick reply after all these years of the issue being closed!

I actually did just that and I'm posting the solution below for anyone else who may be experiencing the same issue in dot net core.

/// <summary>
/// Fixes issue with optional parameters not being generated correctly by Swashbuckle in .NET Core
/// </summary>
public class OptionalParameterOperationFilter : IOperationFilter
{
    /// <summary>
    /// Sets appropriate Required status of parameters
    /// </summary>
    /// <param name="operation">The Swagger operation</param>
    /// <param name="context">The Swagger operation context</param>
    public void Apply(Operation operation, OperationFilterContext context)
    {
        if (operation.Parameters == null)
        {
            return;
        }

        var parameters = context.ApiDescription.ParameterDescriptions;
        foreach (var parameter in parameters)
        {
            var param = operation.Parameters.FirstOrDefault(x => x.Name.ToLowerInvariant() == parameter.Name.ToLowerInvariant());
            if (param == null)
            {
                continue;
            }

            param.Required = parameter.ModelMetadata.IsRequired;
        }
    }
}