I am currently attempting to display a description of a particular response in Swagger UI, but there doesn't seem to be a documentation that truly covers all aspects of that, and all the examples I've tried from Get started with Swashbuckle and ASP.NET Core don't work in .NET Core 3.1...
/// <summary>
/// Test route...
/// </summary>
/// <returns></returns>
/// <response code="200">This is a test</response>
[HttpGet]
[ProducesResponseType(typeof(string), StatusCodes.Status200OK)]
public IActionResult Get()
{
return Ok("Hello World");
}
My .csproj contains the following as well:
<PropertyGroup>
<GenerateDocumentationFile>true</GenerateDocumentationFile>
<NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>
The Swagger UI ends up looking like this (and as you can see, the "Descriptipn" column doesn't contain the "This is a test" text as it probably should). Am I missing something?
I also had added [SwaggerResponse(StatusCodes.Status200OK, ...)]
to it, but nothing changes.
1 - Open the Properties dialog for your project, click the "Build" tab and ensure that "XML documentation file" is checked. This will produce a file containing all XML comments at build-time. At this point, any classes or methods that are NOT annotated with XML comments will trigger a build warning.
The Swagger UI ends up looking like this (and as you can see, the "Descriptipn" column doesn't contain the "This is a test" text as it probably should). Am I missing something? I also had added [SwaggerResponse (StatusCodes.Status200OK, ...)] to it, but nothing changes.
On the other hand, Swagger is a collection of tools for implementing and working with the standard. Some are free, some are open-source, and some are commercial. These tools help us to design, document and consume the REST APIs. In this article, we'll learn how to format text descriptions in our OpenAPI documents. 2. OpenAPI Editors
Let's view the documentation at the default URL http://localhost:8080/swagger-ui/index.html: We can further expand the controller methods to look at their respective documentation. Next, we'll look at them in detail. 4. Making Our Documentation Descriptive
To indicate the response body is empty, do not specify a content for the response: description: The resource was deleted successfully. Responses from an API can include custom headers to provide additional information on the result of an API call. For example, a rate-limited API may provide the rate limit status via response headers as follows:
As it turns out, [SwaggerResponse]
works properly, but before, I need to "enable annotations" in my Startup...
services.AddSwaggerGen(config =>
{
config.SwaggerDoc("v1", new OpenApiInfo
{
Title = "Some API",
Version = "v1"
});
config.EnableAnnotations();
});
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With