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

Question

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; }

I've been working on my fork of Swashbuckle and we added support for examples: https://github.com/heldersepu/Swagger-Net/blob/master/Tests/Swagger.Net.Dummy.Core/Controllers/AnnotatedTypesController.cs#L28 — Helder Sepulveda, Jul 19 '17 at 19:53
I added a full sample under an edit in the original question — Emily Siu, Jul 19 '17 at 20:20
I don't get the use of that "see cref" and I have never seen that PropertyStringAsEnum, can you create a project that reproduces your issue on GitHub? — Helder Sepulveda, Jul 19 '17 at 20:29
"PropertyStringAsEnum" is a custom attribute. Ideally, the cref would be a reference to the other endpoint in Swagger — Emily Siu, Jul 19 '17 at 20:47
Swagger doesn't create a link when I try using unfortunately... — Emily Siu, Jul 19 '17 at 20:59
It works for me (I'm using my own fork) : http://swashbuckletest.azurewebsites.net/swagger/ui/index?filter=IHttpActionResult#/IHttpActionResult/IHttpActionResult_Post — Helder Sepulveda, Jul 19 '17 at 21:02
Also my version uses swagger-ui (3.x), if you want to try it you can get it from: https://www.myget.org/feed/heldersepu/package/nuget/Swagger-Net — Helder Sepulveda, Jul 19 '17 at 21:11
It worked! I have no idea why it didn't previously. Thanks so much. I'll see how I can add the tag programmatically now... — Emily Siu, Jul 19 '17 at 21:15
Great! If you find my answer useful please flag it as correct — Helder Sepulveda, Jul 20 '17 at 01:36

Helder Sepulveda · Accepted Answer · 2017-07-20T01:35:51.910

You can use an ISchemaFilter or an IDocumentFilter to modify the resulting SwaggerDoc.

Here are some samples:

    private class ApplySchemaVendorExtensions : ISchemaFilter
    {
        public void Apply(Schema schema, SchemaRegistry schemaRegistry, Type type)
        {
            // Modify the example values in the final SwaggerDocument
            //
            if (schema.properties != null)
            {
                foreach (var p in schema.properties)
                {
                    switch (p.Value.format)
                    {
                        case "int32":
                            p.Value.example = 123;
                            break;
                        case "double":
                            p.Value.example = 9858.216;
                            break;
                    }
                }
            }
        }
    }

_

    private class ApplyDocumentVendorExtensions : IDocumentFilter
    {
        public void Apply(SwaggerDocument swaggerDoc, SchemaRegistry schemaRegistry, IApiExplorer apiExplorer)
        {
            schemaRegistry.GetOrRegister(typeof(ExtraType));
            //schemaRegistry.GetOrRegister(typeof(BigClass));

            var paths = new Dictionary<string, PathItem>(swaggerDoc.paths);
            swaggerDoc.paths.Clear();
            foreach (var path in paths)
            {
                if (path.Key.Contains("foo"))
                    swaggerDoc.paths.Add(path);
            }
        }
    }

And to add a link just use the anchor tag :

/// <summary>Details - testing anchor: <a href="?filter=TestPost">TestPost</a></summary>

I have a few more examples here: https://github.com/heldersepu/SwashbuckleTest/blob/master/Swagger_Test/App_Start/SwaggerConfig.cs — Helder Sepulveda, Jul 19 '17 at 20:02

score 4 · Answer 2 · answered Apr 13 '22 at 18:26

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; }
}

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>

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.

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.

I tried using a `` but that didn't work. Then noticed you used `` which did work for me inside `
` or `` comments, and worked inside a `SwaggerSchema` attribute. — HappyGoLucky, Aug 23 '22 at 20:50

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

2 Answers2