We Keep Coding

How to add method description in Swagger UI in WebAPI Application

I am using Swagger as my API tooling framework and it is working out great so far. I just came across this page https://petstore.swagger.io/
and saw how each method has a description. For example,
POST: pet/ is described by add a new Pet to the store. I thought adding something like [Description("Description text")] should do it but it just does not. How can I achieve this?

This is well documented in the project:
https://github.com/domaindrivendev/Swashbuckle.AspNetCore#include-descriptions-from-xml-comments
Include Descriptions from XML Comments
To enhance the generated docs with human-friendly descriptions, you can annotate controller actions and models with Xml Comments and configure Swashbuckle to incorporate those comments into the outputted Swagger JSON:
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. To suppress this, enter the warning code "1591" into the "Suppress warnings" field in the properties dialog.
2 - Configure Swashbuckle to incorporate the XML comments on file into the generated Swagger JSON:
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1",
new Info
{
Title = "My API - V1",
Version = "v1"
}
);
var filePath = Path.Combine(System.AppContext.BaseDirectory, "MyApi.xml");
c.IncludeXmlComments(filePath);
}
3 - Annotate your actions with summary, remarks and response tags:
/// <summary>
/// Retrieves a specific product by unique id
/// </summary>
/// <remarks>Awesomeness!</remarks>
/// <response code="200">Product created</response>
/// <response code="400">Product has missing/invalid values</response>
/// <response code="500">Oops! Can't create your product right now</response>
[HttpGet("{id}")]
[ProducesResponseType(typeof(Product), 200)]
[ProducesResponseType(typeof(IDictionary<string, string>), 400)]
[ProducesResponseType(500)]
public Product GetById(int id)
4 - You can also annotate types with summary and example tags:
public class Product
{
/// <summary>
/// The name of the product
/// </summary>
/// <example>Men's basketball shoes</example>
public string Name { get; set; }
/// <summary>
/// Quantity left in stock
/// </summary>
/// <example>10</example>
public int AvailableStock { get; set; }
}
5 - Rebuild your project to update the XML Comments file and navigate to the Swagger JSON endpoint. Note how the descriptions are mapped onto corresponding Swagger fields.
NOTE: You can also provide Swagger Schema descriptions by annotating your API models and their properties with summary tags. If you have multiple XML comments files (e.g. separate libraries for controllers and models), you can invoke the IncludeXmlComments method multiple times and they will all be merged into the outputted Swagger JSON.
Following the instructions carefully you should get something that looks like:
https://swashbucklenetcore.azurewebsites.net/swagger/

For ASP.Net Core projects:
install nuget package Swashbuckle.AspNetCore.Annotations
Use SwaggerOperation attribute for a methods like [SwaggerOperation(Summary = "Write your summary here")]
Enable annotations in Startup method ConfigureServices like the following:
services.AddSwaggerGen(c =>
{
c.EnableAnnotations();
c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
});
To exclude public method from appearing in swagger ui use attribute [ApiExplorerSettings(IgnoreApi = true)]. It is useful cause these methods can break swagger for some reason.
Launch project, go to localhost:[port number]/swagger and enjoy.

We use additional attributes to add required detail to the swagger documentation:
[SwaggerOperationSummary("Add a new Pet to the store")]
[SwaggerImplementationNotes("Adds a new pet using the properties supplied, returns a GUID reference for the pet created.")]
[Route("pets")]
[HttpPost]
public async Task<IHttpActionResult> Post()
{
...
}
And then in you swagger config make sure to apply these filters:
config.EnableSwagger("swagger",
c =>
{
c.OperationFilter<ApplySwaggerImplementationNotesFilterAttributes>();
c.OperationFilter<ApplySwaggerOperationSummaryFilterAttributes>();
The code for the filters:
public class ApplySwaggerImplementationNotesFilterAttributes : IOperationFilter
{
public void Apply(Operation operation, SchemaRegistry schemaRegistry, ApiDescription apiDescription)
{
var attr = apiDescription.GetControllerAndActionAttributes<SwaggerImplementationNotesAttribute>().FirstOrDefault();
if (attr != null)
{
operation.description = attr.ImplementationNotes;
}
}
}
public class ApplySwaggerOperationSummaryFilterAttributes : IOperationFilter
{
public void Apply(Operation operation, SchemaRegistry schemaRegistry, ApiDescription apiDescription)
{
var attr = apiDescription.GetControllerAndActionAttributes<SwaggerOperationSummaryAttribute>().FirstOrDefault();
if (attr != null)
{
operation.summary = attr.OperationSummary;
}
}
}

For those who look for ability to expose custom localized controller names and action descriptions without shipping XML documents to customer and inventing yet another bunch of attrubutes:
public static class SwaggerMiddlewareExtensions
{
private static readonly string[] DefaultSwaggerTags = new[]
{
Resources.SwaggerMiddlewareExtensions_DefaultSwaggerTag
};
public static void ConfigureSwagger(this IServiceCollection services)
{
services
.AddSwaggerGen(options =>
{
options.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo
{
Title = "My API",
Version = "v 1.0"
});
// your custom config
// this will group actions by localized name set in controller's DisplayAttribute
options.TagActionsBy(GetSwaggerTags);
// this will add localized description to actions set in action's DisplayAttribute
options.OperationFilter<DisplayOperationFilter>();
});
}
private static string[] GetSwaggerTags(ApiDescription description)
{
var actionDescriptor = description.ActionDescriptor as ControllerActionDescriptor;
if (actionDescriptor == null)
{
return DefaultSwaggerTags;
}
var displayAttributes = actionDescriptor.ControllerTypeInfo.GetCustomAttributes(typeof(DisplayAttribute), false);
if (displayAttributes == null || displayAttributes.Length == 0)
{
return new[]
{
actionDescriptor.ControllerName
};
}
var displayAttribute = (DisplayAttribute)displayAttributes[0];
return new[]
{
displayAttribute.GetName()
};
}
}
where DisplayOperationFilter is:
internal class DisplayOperationFilter : IOperationFilter
{
public void Apply(OpenApiOperation operation, OperationFilterContext context)
{
var actionDescriptor = context.ApiDescription.ActionDescriptor as ControllerActionDescriptor;
if (actionDescriptor == null)
{
return;
}
var displayAttributes = actionDescriptor.MethodInfo.GetCustomAttributes(typeof(DisplayAttribute), false);
if (displayAttributes == null || displayAttributes.Length == 0)
{
return;
}
var displayAttribute = (DisplayAttribute)displayAttributes[0];
operation.Description = displayAttribute.GetDescription();
}
}
Applicable for Swashbuckle 5.

A workaround is to add this to your .csproj file:
<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|AnyCPU' ">
<DocumentationFile>bin\Debug\netcoreapp1.1\FileXMLName.xml</DocumentationFile>
</PropertyGroup>

You can use comment for documentation (3 slashes instead of standard 2) like:
/// <summary>
/// This is method summary I want displayed
/// </summary>
/// <param name="guid">guid as parameter</param>
/// <param name="page_number">Page number - defaults to 0</param>
/// <returns>List of objects returned</returns>

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

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

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.

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: TestPost</summary>

json.net Schema IsValid slow

I have a web service that communicates with client with JSON messages, the run-time itself is not aware of the data-model which is why I use json.net Schema to validate messages from client and inside the service itself, however Its causing a great amount of overhead in terms of performance.
Simplified code that still contain enough context to understand what I am doing.
public class Template
{
/// <summary>
/// Template known as
/// </summary>
public string Name { get; private set; }
/// <summary>
/// Razor Template
/// </summary>
public string RazorTemplate { get; private set; }
/// <summary>
/// Json Schema definition
/// </summary>
public string Schema { get; private set; }
private JSchema _schema { get; set; }
private JSchema JSchema
{
get
{
if (_schema == null)
_schema = JShema.Parse(Schema);
return _schema;
}
}
private void Validate(JObject obj)
{
// Schema validation Error messages.
IList<string> ValidationError;
// Schema validation.
if (!obj.IsValid(JSchema, out ValidationError))
{
throw new Exception(string.Join(",", ValidationError.ToArray()));
}
}
public string RunTemplate(JObject jobj)
{
// Validate Json Object.
Validate(jobj);
// Code here that access our RazorEngine cache, and add then run Razor Template, or directly run a cached Razor Template...
return "Here we return string generated by RazorEngine to sender.";
}
}
Lets say i run a simple "Hello #Model.Name!" template that validates that json has string Name this is 15-20 times slower then if i comment out validation entirely.
Are there more efficient ways to use IsValid in Json.Net Schema?

Make sure you update to the latest version of Json.NET Schema available on NuGet, performance was slow when validating certain schemas with older versions.
Also there is documentation on the Json.NET Schema website for performance best practices.

ASP.NET Web API Help Page can't process Generic Type Controller

I have a question about ASP.NET Web API HelpPages.
Usually HelpPages can generate the WebAPI by XMLDocumentation
Sample Code:
public class ValueControllerBase : ApiController
{
/// <summary>
/// Base Do
/// </summary>
public IEnumerable<string> Do()
{
return new string[] { "value1", "value2" };
}
}
public class ValuesController : ValueControllerBase
{
/// <summary>
/// Testing API
/// </summary>
public string Get(int id)
{
return "value";
}
}
this can generate successfully, like this:
API
GET api/Values/Get/{id}
Description
Testing API
API
POST api/Values/Do
Description
Base Do
but if I use a generic base controller, it will not generate the API Document.
Sample:
public class ValueControllerBase<T> : ApiController
{
/// <summary>
/// Base Do
/// </summary>
public IEnumerable<string> Do()
{
return new string[] { "value1", "value2" };
}
}
public class ValuesController<String> : ValueControllerBase
{
/// <summary>
/// Testing API
/// </summary>
public string Get(int id)
{
return "value";
}
}
If I use the code at the second section, HelpPages can generate the API document, but doesn't generate the API annotation. The difference between my two examples is just second section code use a generic type.
API
GET api/Values/Get/{id}
Description
Testing API
API
POST api/Values/Do
Description
null
In the method Do(), the annotation doesn't display compared with the first
Is there any solution to fix these problems?

I was able to solve this by adjusting some code in the XmlDocumentationProvider.
The original implemention of XmlDocumentationProvider.GetTypeName(Type) is the following:
private static string GetTypeName(Type type)
{
string name = type.FullName;
if (type.IsGenericType)
{
// Format the generic type name to something like: Generic{System.Int32,System.String}
Type genericType = type.GetGenericTypeDefinition();
Type[] genericArguments = type.GetGenericArguments();
string genericTypeName = genericType.FullName;
// Trim the generic parameter counts from the name
genericTypeName = genericTypeName.Substring(0, genericTypeName.IndexOf('`'));
string[] argumentTypeNames = genericArguments.Select(t => GetTypeName(t)).ToArray();
name = String.Format(CultureInfo.InvariantCulture, "{0}{{{1}}}", genericTypeName, String.Join(",", argumentTypeNames));
}
if (type.IsNested)
{
// Changing the nested type name from OuterType+InnerType to OuterType.InnerType to match the XML documentation syntax.
name = name.Replace("+", ".");
}
return name;
}
I don't know why, but they attempt to create the type name for the xml lookup to include the actual generic attributes, rather than the generic type name itself (for example, they create Nullable{bool} rather than Nullable`1). Only the generic name itself is defined in the xml file.
A simple change to the code gets it to name/reference the documentation for the generic class correctly:
....
if (type.IsGenericType)
{
Type genericType = type.GetGenericTypeDefinition();
name = genericType.FullName;
}
....
After making that change, the annotations began to display correctly for generics types, and for me, this didn't break anything else either.

How do you do web forms model validation?

We have an application with three layers: UI, Business, and Data. The data layer houses Entity Framework v4 and auto-generates our entity objects. I have created a buddy class for the entity VendorInfo:
namespace Company.DataAccess
{
[MetadataType(typeof(VendorInfoMetadata))]
public partial class VendorInfo
{
}
public class VendorInfoMetadata
{
[Required]
public string Title;
[Required]
public string Link;
[Required]
public string LinkText;
[Required]
public string Description;
}
}
I want this validation to bubble up to the UI, including custom validation messages assigned to them. In MVC this is a piece of cake but in web forms I have no clue where to begin. What is the best way to utilize model validation in asp.net web forms?
I did find an article that explains how to build a server control for it, but I can't seem to get it working. It compiles and even recognizes the control but I can never get it to fire.
Any ideas?
Thanks everyone.

I solved it. It would appear that the server control I found was not designed to read fields in a buddy class via the MetadataType attribute. I modified the code to look for its validation attributes in the buddy class rather than the entity class itself.
Here is the modified version of the linked server control:
[DefaultProperty("Text")]
[ToolboxData("<{0}:DataAnnotationValidator runat=server></{0}:DataAnnotationValidator>")]
public class DataAnnotationValidator : BaseValidator
{
#region Properties
/// <summary>
/// The type of the source to check
/// </summary>
public string SourceTypeName { get; set; }
/// <summary>
/// The property that is annotated
/// </summary>
public string PropertyName { get; set; }
#endregion
#region Methods
protected override bool EvaluateIsValid()
{
// get the type that we are going to validate
Type source = GetValidatedType();
// get the property to validate
FieldInfo property = GetValidatedProperty(source);
// get the control validation value
string value = GetControlValidationValue(ControlToValidate);
foreach (var attribute in property.GetCustomAttributes(
typeof(ValidationAttribute), true)
.OfType<ValidationAttribute>())
{
if (!attribute.IsValid(value))
{
ErrorMessage = attribute.ErrorMessage;
return false;
}
}
return true;
}
private Type GetValidatedType()
{
if (string.IsNullOrEmpty(SourceTypeName))
{
throw new InvalidOperationException(
"Null SourceTypeName can't be validated");
}
Type validatedType = Type.GetType(SourceTypeName);
if (validatedType == null)
{
throw new InvalidOperationException(
string.Format("{0}:{1}",
"Invalid SourceTypeName", SourceTypeName));
}
IEnumerable<MetadataTypeAttribute> mt = validatedType.GetCustomAttributes(typeof(MetadataTypeAttribute), false).OfType<MetadataTypeAttribute>();
if (mt.Count() > 0)
{
validatedType = mt.First().MetadataClassType;
}
return validatedType;
}
private FieldInfo GetValidatedProperty(Type source)
{
FieldInfo field = source.GetField(PropertyName);
if (field == null)
{
throw new InvalidOperationException(
string.Format("{0}:{1}",
"Validated Property Does Not Exists", PropertyName));
}
return field;
}
#endregion
}
This code only looks in the buddy class. If you want it to check an actual class and then its buddy class, you'll have to modify it accordingly. I did not bother doing that because usually if you are using a buddy class for validation attributes it's because you are not able to use the attributes in the main entity class (e.g. Entity Framework).

For model validation in web forms I'm using DAValidation library. It supports validation on client side (including unobtrusive validation), extensibility based on same principles as in MVC. It is MS-PL licensed and available via Nuget.
And here is bit out of date article describing with what thoughts control was build.