Swashbuckle / swagger Document missing information

Question

I can't seem to understand why my swagger doc UI is missing the Model Schema details for each Gets and Posts within my controller?

I am running SwashBuckle for ASP.NET core nuget package v4.0.1 and even after upgrading to the latest package does nothing to show the schema details? (My WebAPI is build in Core 2.2)

I have ran through the swagger documentation only w.r.t configurations and nothing directs me to where I can get the additional information to be displayed?

After some research I found that if I use the following Attribute

[ProducesResponseType(typeof(Models.Customer), StatusCodes.Status200OK)]
[HttpGet("{Id}/customer")]
public async Task<IActionResult> GetCustomer(int Id)

Displays Schemas block in the swagger UI which is exactly I want. However I don't want to go through each of my Controller Get / Post methods and add this attribute. It always worked without this but what could be preventing this from working out of the box?

Using the `[ProducesResponseType]` is the only way with Swashbuckle for dotnet core, AFAIK. I haven't seen it done otherwise (but am intrigued that it'd work for you in the past?). For those interested, a complete Swashbuckle example can be found in [this related post](https://stackoverflow.com/questions/37681023/swashbuckle-parameter-descriptions/42022793#42022793). — Juliën, Dec 20 '19 at 12:27
I did have a similar case. My Return-Types were missing get; set; for the properties. — ralf.w., Aug 17 '20 at 07:27

score 3 · Accepted Answer · answered Dec 20 '19 at 12:36

3

Swashbuckle creates the model based on the action's return type. You have several options:

You can return the actual type (e.g. public async Task<Models.Customer> GetCustomer(int Id)
If you return an IActionResult, you can use the ProducesResponseType attribute
You can return an ActionResult<T> which works just like the IActionResult but with the actual type

You can check the documentation for more information: https://learn.microsoft.com/en-us/aspnet/core/web-api/action-return-types?view=aspnetcore-3.1

answered Dec 20 '19 at 12:36

Métoule

13,062
2
56
84

1

Thank you @Metoule Very well explained. I went for the third option and it worked well :) However I feel `ProducesResponseType` may suit me more as in my method I return a Ok status e.g. `Return Ok()` and swagger documentation translates it as Response Success. – KJSR Dec 20 '19 at 12:41

score 0 · Answer 2 · edited Feb 05 '21 at 23:43

So, your method returns IActionResult, it is a common thing and the compiler cannot see what real result will be returned. That's why you should use ProducesResponseType.

If you want to use IActionResult and Asp.Net MVC controllers it is only this way to use.

But another point is: do you really need Asp.Net MVC controllers? And if you need Asp.Net MVC controllers why do you want to create swagger documentation? These things are contradictionary.

Swagger needs to create Public Api Documentation. To add possibility for external programmers to use your API. And in this case it is better to use Api controllers.

If you need to use Asp.Net MVC controllers with that features like Autorization, then you don't need to create Swagger, because it should be used in your own project.

Swashbuckle / swagger Document missing information

2 Answers2