Add links in description to other operations in Swagger (through Swashbuckle)

user_6263260 0
Viewed 5436

According to the documentation for Swashbuckle, only a few XML comments are supported in the latest version. It seems like XML comments such as <example> or <see> are not currently supported but will be implemented in Swashbuckle v6.

Until then, is there a workaround I can do to mimick the behavior of <example> or <see>?

I'd like to somehow add a link (using <see> with cref) in the <summary> of an enum, which is listed under the model of an endpoint, to point to the enum's corresponding endpoint (a different endpoint in Swagger that gets the list of types of that enum).

Edit (not sure how to format in comment):

I'd like Swagger to detect <see> and display a link in the enum's description to a different endpoint 

/// <summary>
/// Generic description. 
/// Find enum types <see cref="ContactEntityType">here</see>
/// </summary>
[PropertyRequired, PropertyStringAsEnum(typeof(ContactEntityType))]
[DataMember(Name = "entityType")]
public NamedReference EntityType { get; set; }
swagger swashbuckle enums c#
2 Answers

In 2022 the latest version of swagger supports parameter comments.

/// <param name="MyParamaterName" example="123"> Should be defined as model MyModelName</param>
[HttpPost]
[Route("SomeWebApiFunction")]
public async Task<bool> SomeWebApiFunction(MyModelName MyParamaterName)
{
    return true;
}

public class MyModelName
{
    public string PropName { get; set; }
}

enter image description here

Swaggers pretty good at giving each section a unique id, you can check each sections id attribute with the inspect element. This makes it pretty easy to link around the document. For example we could add a link to scroll to the MyModelName description;

/// <param name="MyParamaterName" example="123"> Should be defined as model <a href='#model-MyModelName'>MyModelName</a></param>

enter image description here

Don't forget to IncludeXmlComments

builder.Services.AddSwaggerGen(c => {
    string fileName = $"{System.Reflection.Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var filePath = Path.Combine(AppContext.BaseDirectory, fileName);
    c.IncludeXmlComments(filePath);
});

If your using Visual Studio, be sure Generate XML comments are turned on.

enter image description here

If your using Asp.net Core and the xml is not being generated, you have to add the following line within the PropertyGroup of your .csproj file.

<PropertyGroup>  
<DocumentationFile>bin\$(Configuration)\$(TargetFramework)\YourApplicationNameGoesHere.xml</DocumentationFile>
</PropertyGroup>

Replace YourApplicationNameGoesHere with the name of your application. If for some reason you do not know the xml file name, you can find it in the output folder of your project build.

user_5912850
Related