Swashbuckle / swagger 文档缺失信息

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 wrt 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?

Answer 1

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

• You can return the actual type (eg 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://docs.microsoft.com/en-us/aspnet/core/web-api/action-return-types?view=aspnetcore-3.1

Answer 2

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.