Swagger annotation for file parameter?

ServiceStack Swagger
1

Is there a way to add an annotation so that the generated Swagger definition that documents the fact that a specific service is expecting a file to posted along with the rest of the parameters?

Thanks,
Jon…

2

Hi Jon,

I’ve not tried it before but it sounds like you should be able to specify DataType="file": http://stackoverflow.com/a/15087260/85785

3

Yeah, I had found that as well; however since you normally don’t add a property to the request POCO for the file being uploaded, where would I attach the annotation to?

4

Yeah that would be tricky. If the property doesn’t exist the only way to add it to the Swagger metadata is with a filter, e.g:

Plugins.Add(new SwaggerFeature
{
    OperationFilter = op => {
        if (op.Nickname == typeof(UploadFile).Name && op.Method == HttpMethods.Post)
        {
            op.Parameters.Add(new SwaggerParameter {
                Name = "upload",
                ParamType = "body",
                Type = "file"
            });
        }
    },
});

Note: OperationFilter was added in the latest v4.0.54 release

1 Like
5

That’ll work perfect for me. Thanks!

1 Like
6

Is there a similar annotation for Password type so that password isn’t visible as plain text in auth?

7

@maggarwal It’s not in the Swagger 1.2 spec and using DataType or Format of “password” doesn’t have any impact.

8

This is exactly what I need but for OpenAPI - could you port this snippet to OpenAPI?

I believe ParamType = “body” needs to be replaced with In = “formData” but not clear on the op.Nickname and op.Method since those properties dont exist on an OpenApi Operation.

thanks!

9

Taken from Open API 2.0 documentation I believe filter for uploading files should look like that

OperationFilter = (verb, op) => {
     if (op.OperationId.StartsWith(typeof(UploadFile).Name + "_") && verb.ToUpper() == HttpMethods.Post)
     {
          op.Parameters.Add(new OpenApiParameter {
                Name = "upload",
                In = "formData",
                Type = "file",
                Description = "the file to upload"
          });
          op.Consumes = new [] { "multipart/form-data" }
     }
}
10

Thanks - works a charm!

In case it helps anyone else, you need to modify the string match there on the OperationId to match your path/request object.

11

Is there any way to specify multiple attribute for this?

something like

<input type="file" name="img" multiple>
12

Don’t think so