Remove "default" Response Message from Swagger UI

ServiceStack Open API
1

I’ve been using Swagger on Core MVC for a while but now we’re moving over to ServiceStack. I’m currently stuck on trying to document the response type from a POST endpoint while returning a 201 status code.

In Core MVC I could use this attribute:

[ProducesResponseType(typeof(CreateCustomerCommand.Result), 201)]

I closest I have gotten is using this attribute:

[ApiResponse(HttpStatusCode.Created, "Created")]

But I end up with the response model under “default” instead of my 201 response in Swagger.

Is it possible to remove “default” from a service that only returns a NoContent response? I am hoping I am missing some kind of magic sauce to remove it.

image.png886×196 12.1 KB

ServiceModel

[Route("/Text/Message/Sessionkey/{SessionKey}", "DELETE", 
    Summary = @"Delete a ZipWhip session key")]
[ApiResponse(HttpStatusCode.NoContent, "No Content")]
[Authenticate, RequiresScopes(Scope.ZipWhipAllow, Scope.FullAccess)]
public class DeleteSessionKey : IDelete
{
    public string SessionKey { get; set; }
}

ServiceInterface

    public async Task Delete(DeleteSessionKey req)
    {
        /// ...
        return;
    }

Is there any way to change “default” to mirror what is actually being returned, HTTP Status Code 200?

If I add an ApiResponse attribute then I end up with this:

ASP.NET Core MVC does this automatically.

Thanks… -Paul

2

Can you please consolidate your last 3 posts into a single post? they’re all referencing the same issue, it’s much easier for everyone to follow if there was a single thread for this issue everyone can focus on.

The way to denote a Service has no response is to use the IReturnVoid interface marker, e.g:

public class DeleteSessionKey : IDelete, IReturnVoid
{
    public string SessionKey { get; set; }
}

But how the Service is represented in Swagger UI is separate issue which @xplicit will take a look at once he wakes up. In the meantime can you add a link (e.g. in a gist or pastebin) to the Open API .json MVC generates for their API?

3

I guess my other posts look similar, I’ll continue with this one and if it solves the other two I’ll consolidate but I think it’s slightly different issues.

Anyway…

I have the correct marker interfaces on the DTO, just like you posted. The service responds accordingly with a 204 and no content but swagger doesn’t mimic that. When I remove [ApiResponse(HttpStatusCode.NoContent, "No Content")] I end up with this:

Where I expect something like this:

Pastebin for my latest OpenApi json: https://pastebin.com/eUL8aKU5

-Paul

4

Just edit your original post to include all questions, which just looks like how to get the desired Swagger response from your Service that returns no content. You can just add additional comments if there are any remaining questions.

5

You can change default response to 200 by using OpenApiOperation filters.

Plugins.Add(new OpenApiFeature
{
    OperationFilter = (verb, op) =>
    {
        var response = op.Responses["default"];
        op.Responses.Remove("default");
        op.Responses.Add("200", response);
    }
});

About second part of the issue: I’m adding the ability to make responses more customizable via [ApiResponse] tag

6

That’s good news, thanks for modifying the ApiResponse attribute, it’ll make our public API documentation much cleaner. -Paul

7

I made some changes how OpenApi plugin handles responses:

Now response has got HTTP code 200 by default instead of “default” and it’s shown on top of Swagger UI operation.

annotated-1.PNG964×320 8 KB

To use “default” response which was used previously you have to annotate Request DTO by [ApiResponse] with IsDefaultResponse = true property.

    [Route("/return-annotated", "GET")]
    [ApiResponse(Description = "Default Response", IsDefaultResponse = true)]
    public class ReturnAnnotatedDtoRequest : IReturn<Return200Response>
    {
        public int Code { get; set; }
    }

It’s possible to select response type for [ApiResponse] attribute by using ResponseType property.

[ApiResponse(Status = 403, Description = "Forbidden Service", ResponseType = typeof(ForbiddenResponse)]

annotated-2.PNG834×207 6.11 KB

Services which return IReturnVoid now use empty responses in Swagger UI. Status code depends on Config.Return204NoContentForEmptyResponse setting. If this setting is set to true (default value) then 204 status is used in Open API specification, otherwise status code 200 is used.

    [Route("/return-void")]
    public class ReturnVoidDtoRequest : IReturn<IReturnVoid> {}

annotated-3.PNG965×312 11.7 KB

These changes are available on MyGet since v 4.5.13

8

This is awesome Sergey, thank you for the quick turn around. -Paul