Im Beitrag unter [1] habe ich gezeigt, wie man mit Routing-Constraints Web APIs versionisieren kann. Die in den Controllern hinterlegten Versionsnummern können auch von Swashbuckle [2] genutzt werden, um herauszufinden, welche Action-Methode zu welcher Version der Swagger-Dokumention gehört. Dazu implementiert man eine Methode mit der nachfolgend gezeigten Signatur. Sie nimmt die Beschreibung einer Action-Methode sowie eine Version entgegen und liefert true, falls die Methode in der Dokumentation der jeweiligen Version aufscheinen soll. Hierzu greift die hier gezeigte Methode auf die Eigenschaft Version des Attributs VersionedRoute zu:
private static bool ResolveVersionSupportByRouteConstraint(
ApiDescription apiDesc,
string targetApiVersion)
{
var attr = apiDesc
.ActionDescriptor
.GetCustomAttributes<VersionedRoute>()
.FirstOrDefault();
if (attr == null) return true;
return attr.Version == targetApiVersion;
}
Um Swashbucke nun Informationen über die vorliegenden Versionen zukommen zu lassen, nutzt man in der Konfiguration die Methode MultipleApiVersions. Der erste übergebene Lambda-Ausdruck delegiert an die zuvor diskutierte Funktion weiter; der zweite registriert die einzelnen Versionen. Die standardmäßig genutzte Methode SingleApiVersion, welche zum Einsatz kommt, wenn nur eine Version vorliegt, wird hingegen nicht mehr aufgerufen.
// Diese Zeile auskommentieren:
// c.SingleApiVersion("v1", "VersioningSample");
c.MultipleApiVersions(
(apiDesc, targetApiVersion) => ResolveVersionSupportByRouteConstraint(apiDesc, targetApiVersion),
(vc) =>
{
vc.Version("3", "Swashbuckle Voucher API V3");
vc.Version("2", "Swashbuckle Voucher API V2");
vc.Version("1", "Swashbuckle Voucher API V1");
});
Hat das funktioniert, erhält man beim Aufrufen der Swagger-Dokumentation zunächst nur Informationen zur neuesten Version:
Gibt man in der Url eine andere Versionsnummer an, bekommt man die hierzu passenden Methoden:
Wer eventuelle Versionsnummern, die in den Klassennamen der Controller auftauchen, verbergen möchte, kann in der Swashbuckle-Konfiguration eine eigene Gruppierung für die Action-Methoden festlegen. Das nachfolgende Beispiel gruppiert die Methoden nach dem Controller-Namen, entfernt jedoch zuvor einen eventuellen Suffix, welcher aus Ziffern besteht. Dabei liegt die Annahme zugrunde, dass solch ein Suffix eine Versionsnummer wiederspiegelt.
c.GroupActionsBy(apiDesc => {
var name = apiDesc.ActionDescriptor.ControllerDescriptor.ControllerName;
name = Regex.Replace(name, @"^(.*?)([\d]*)$", @"$1");
return name;
});
[1] http://www.softwarearchitekt.at/post/2015/07/14/web-apis-versionisieren.aspx
[2] http://www.softwarearchitekt.at/post/2015/06/15/web-apis-mit-swagger-dokumentieren.aspx