Generated swagger/redoc page doesn't respect inherited descriptions

[gfoidl]

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

[captainsafia]

This looks like a dupe of domaindrivendev/Swashbuckle.AspNetCore#2597.

At the moment, we don't support generating OpenAPI descriptions from XML by default in the framework. We've got #39927 but this will have to be fixed in Swashbuckle.AspNetCore for now.

The issue linked above seems to indicate that NSwag has the correct behavior here. Have you given that a try?

[senketsu03]

I haven't yet tried out NSwag, but I'd prefer to use Swashbuckle.AspNetCore if possible, since NSwag seems to rely on Newtonsoft.Json. I'm trying to use System.Text.Json only for all my json-related work

[captainsafia]

I haven't yet tried out NSwag, but I'd prefer to use Swashbuckle.AspNetCore if possible, since NSwag seems to rely on Newtonsoft.Json. I'm trying to use System.Text.Json only for all my json-related work

Understandable. For now, I think it's best to file an issue on the Swashbuckle.AspNetCore repo since the fix will need to be made there.

[ghost]

We've moved this issue to the Backlog milestone. This means that it is not going to be worked on for the coming release. We will reassess the backlog following the current release and consider this item at that time. To learn more about our issue management process and to have better expectation regarding different types of issues you can read our Triage Process.

[captainsafia]

Hi all,

We've outlined our future plans for the OpenAPI area in ASP.NET Core in this announcement issue. Moving forward, we're hoping to add OpenAPI document generation support as a first-class feature in ASP.NET Core and eventually add support for XML doc comments as outlined above.

With this in mind, I'm going to close this issue and use the existing XML issue to track work in this area.