Generated swagger/redoc page doesn't respect inherited descriptions #48982
Description
Discussed in #48978
Originally posted by @senketsu03 June 23, 2023
Consider writing an abstract class/interface and adding summary to a method like so:
/// <summary>
/// Add user to database
/// </summary>
/// <param name="user">User to add</param>
/// <remarks>
///
/// Minimal request:
///
/// POST /users
/// { }
///
/// </remarks>
public Task<ActionResult<User>> PostUserAsync(User user);Implementing it method with all needed attributes works as expected, but the docs are not visible on swagger/redoc pages, even when <inheritdoc/> is added.
I've also tried experimenting with writing sharable API in form of library/nuget package. Let's say it has a complete controller in this library:
/// <summary>
/// User controller
/// </summary>
[ApiController]
[ApiConventionType(typeof(DefaultApiConventions))]
[Route("/users")]
public class UserController : ControllerBase
{
private readonly Context _context;
public UserController(Context context) => _context = context;
/// <summary>
/// Get user from database by id
/// </summary>
/// <param name="id">User's id</param>
/// <returns>User or response state</returns>
[HttpGet("{id}")]
[Produces(MediaTypeNames.Application.Json)]
public async Task<ActionResult<User>> GetUserAsync(int id)
{
var user = await Library.GetUserAsync(_context, id).ConfigureAwait(false);
if (user is null)
return BadRequest(new ProblemDetails { Detail = $"Object with id={id} doesn't exist" });
else
return Ok(user);
}
}Then, referencing this library from webapi server will show all referenced controllers and methods on a swagger page, but again -- they lack documentation