swagger - How to spec base64 encoded object in query param in OpenAPI

Question

I am trying to document an existing API using the OpenAPI spec (specifically using Swashbuckle and ASP.NET Core). For many of the endpoints, the api uses a single query parameter which is a filter object – holding the actual parameters – that is base64-encoded.

I have successfully added the Swashbuckle library and can generate a swagger.json.

The generated spec however does not correctly describe the endpoints described above. Rather, the property names of the filter object are stated as query parameters, and thus autogenerated clients based off the spec do not work.

The spec mentions base64 only in relation to format of String and File, not Object.

1. Is it possible (and if so, how) to describe this type of endpoint in OpenAPI?

2. Is it possible (and if so, how) to generate this description correctly using Swashbuckle?

EDIT

In response to comment (probably necessary for answering subquestion 2) ).

An endpoint in the API source may look something like:

[HttpGet("")]
public async Task<IActionResult> Query([FromQuery] ThingFilter filter)
{
    var results = await _dataContext.ThingService.Search(filter);
    
    return Ok(results);
}

And a ThingFilter might be something like:

public class ThingFilter
{
    public string Freetext { get; set; }
    public List<PropertyFilter> PropertyFilters { get; set; }
}

In Startup.cs there is also registered a custom modelbinder that handles conversion from base64.

question from:https://stackoverflow.com/questions/65848807/how-to-spec-base64-encoded-object-in-query-param-in-openapi

Answer 1

Waitting for answers