admin管理员组文章数量:1032385
在Sitecore8.2解决方案中使用Swagger作为API管理工具
假设您的Sitecore解决方案需要一些API服务。显而易见的是使用 Web API实现它们。有时，在构建消费应用程序时，理解API的各种方法对开发人员来说可能是一项挑战。
假设您的Sitecore解决方案需要一些API服务。显而易见的是使用 Web API实现它们。有时，在构建消费应用程序时，理解API的各种方法对开发人员来说可能是一项挑战。Swagger 是RESTful API的机器可读表示， 支持交互式文档，客户端SDK生成和可发现性。
使用Swagger
使用Swagger为Web API生成良好的文档和帮助页面就像添加NuGet包一样简单。
只要Sitecore仍然是一个asp应用程序，我们就可以使用Swagger！所以我实现了一个Web API控制器，我希望在我的Sitecore实例中托管它并以某种方式记录它：
代码语言：javascript代码运行次数：0运行复制namespace Feature.WebApi.Controllers
{
using System.Web.Http;
[RoutePrefix("-/api/v1")]
public class MyServicesApiController : ApiController
{
[HttpGet]
[Route("hello-world")]
public IHttpActionResult HelloWorld()
{
return this.Ok("Hello world");
}
}
}好的，这是我的“hello world”API方法。现在我将使用nuget将Swagger安装到我的Feature.Swagger项目中：
代码语言：javascript代码运行次数：0运行复制install-package Swashbuckle默认的nuget包将在/App_Start/SwaggerConfig.cs中创建启动配置。默认情况下，它使用WebActivator扩展将其绑定到应用程序启动，以便在初始化Web应用程序时执行配置。
默认情况下，它不能与Sitecore平稳运行，但我们可以使用少量配置使其正常工作。Swagger UI的入口点是{your.domain} / swagger。我跑了，看下一张图：
为了解决它，我们需要修改/App_Start/SwaggerConfig.cs并取消注释下一行：
代码语言：javascript代码运行次数：0运行复制c.ResolveConflictingActions(apiDescriptions => apiDescriptions.First());再次运行 - 我们看到下一个问题：
这次我们需要取消注释另一行配置：
代码语言：javascript代码运行次数：0运行复制c.UseFullTypeNameInSchemaIds();好的，现在它已启动并运行，但是底部有一个annoing错误，表示存在架构验证错误。Swagger UI仍然有效，但我们真的不想看到任何错误消息吗？我们可以通过取消另外一行配置来绕过它：
代码语言：javascript代码运行次数：0运行复制c.DisableValidator();Web API服务
现在它查找并运行，我甚至能够找到我的服务方法。但是，Sitecore有很多自己使用的Web API服务，很难找到我自己的服务。将Sitecore本机Web API控制器与我的分离是很好的。它支持API版本控制，从我的角度来看，这是我们如何分离它的方法之一。我们可以向SwaggerConfig添加一个方法，该方法将声明API的版本。
我将Sitecore服务称为版本“ sc ”，将我自己称为“ my_services ”：
代码语言：javascript代码运行次数：0运行复制private static bool ResolveVersionSupportByRouteConstraint(ApiDescription apiDesc, string targetApiVersion)
{
if (apiDesc.Route.RouteTemplate.StartsWith("-/api/v1") && targetApiVersion == "my_services") return true;
if (apiDesc.Route.RouteTemplate.StartsWith("sitecore") && targetApiVersion == "sc") return true;
return false;
}在配置中，我们需要注释/删除此行
代码语言：javascript代码运行次数：0运行复制c.SingleApiVersion("v1", "Feature.Swagger");并添加这个：
代码语言：javascript代码运行次数：0运行复制c.MultipleApiVersions(
ResolveVersionSupportByRouteConstraint,
vc =>
{
vc.Version("my_services", "My services API (you can switch to Sitecore API /swagger/docs/sc)");
vc.Version("sc", "Sitecore services (you can switch to My services API /swagger/docs/my_services)");
});现在我们为Sitecore API和My API提供了2个独立的视图。它们被Swagger UI视为API版本：
安装
或许，公开提供该文档并不是一个好主意，因为它会产生安全问题。因此，我们需要做的是在登录后隐藏Swagger UI，并使其仅供Sitecore管理员用户使用。我们可以重新使用Sitecore的默认登录页面。从我的角度来看，最好的方法是使用HTTP MessageHandlers。我们可以实现下一个消息处理器
代码语言：javascript代码运行次数：0运行复制namespace Feature.Swagger
{
using System;
using System.Net;
using System.Net.Http;
using System.Threading;
using System.Threading.Tasks;
using Sitecore;
public class SwaggerSitecoreAuthMessageHandler : DelegatingHandler
{
protected override Task SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
{
var isAuthenticated = Context.User?.IsAuthenticated ?? false;
var isAdministrator = Context.User?.IsAdministrator ?? false;
if (this.IsSwaggerRequest(request) && (!isAuthenticated || !isAdministrator))
{
var response = new HttpResponseMessage(HttpStatusCode.Redirect);
var uri = request.RequestUri;
var currentOrigin = uri.AbsoluteUri.Replace(uri.PathAndQuery, string.Empty);
var logiPage = currentOrigin + @"/sitecore/login?returnurl=/swagger";
response.Headers.Location = new Uri(logiPage);
return Task.FromResult(response);
}
else
{
return base.SendAsync(request, cancellationToken);
}
}
private bool IsSwaggerRequest(HttpRequestMessage request)
{
return request.RequestUri.PathAndQuery.ToLowerInvariant().StartsWith("/swagger");
}
}
}然后在SwaggerConfig类中添加一行，如下所示：
代码语言：javascript代码运行次数：0运行复制GlobalConfiguration.Configuration.MessageHandlers.Add(new SwaggerSitecoreAuthMessageHandler());现在我们已成功将Swagger安装到Sitecore解决方案中。但是，正如我之前提到的，它使用WebActivator扩展，这更像是Web解决方案的反模式，我最好摆脱它，以保持螺旋原则。相反，我们可以使其更多Sitecore本地方式 - 在Sitecore初始化管道上运行配置。
所以首先我们要做的是删除这一行：
代码语言：javascript代码运行次数：0运行复制[assembly: PreApplicationStartMethod(typeof(SwaggerConfig), "Register")]然后创建一个运行初始化的超简单初始化管道处理器：
代码语言：javascript代码运行次数：0运行复制namespace Feature.Swagger.Pipelines.Initialize
{
using Sitecore.Pipelines;
public class InitializeSwagger
{
public void Process(PipelineArgs args)
{
SwaggerConfig.Register();
}
}
}当然我们需要将它添加到配置文件/App_Config/Include/Feature/Feature.Swagger.config中：
代码语言：javascript代码运行次数：0运行复制<?xml version="1.0" encoding="utf-8" ?>
<configuration xmlns:patch="/" xmlns:set="/">
<sitecore>
<pipelines>
<initialize>
<processor type="Feature.Swagger.Pipelines.Initialize.InitializeSwagger, Feature.Swagger" />
</initialize>
</pipelines>
</sitecore>
</configuration>最后，我的完整SwaggerConfig.cs文件如下所示：
代码语言：javascript代码运行次数：0运行复制namespace Feature.Swagger
{
using System.Web.Http;
using System.Linq;
using Swashbuckle.Application;
using System.Web.Http.Description;
public class SwaggerConfig
{
public static void Register()
{
var thisAssembly = typeof(SwaggerConfig).Assembly;
GlobalConfiguration.Configuration.MessageHandlers.Add(new SwaggerSitecoreAuthMessageHandler());
GlobalConfiguration.Configuration
.EnableSwagger(c =>
{
c.MultipleApiVersions(
ResolveVersionSupportByRouteConstraint,
vc =>
{
vc.Version("my_services", "My services API (you can switch to Sitecore API /swagger/docs/sc)");
vc.Version("sc", "Sitecore services (you can switch to My services API /swagger/docs/my_services)");
});
c.UseFullTypeNameInSchemaIds();
c.ResolveConflictingActions(apiDescriptions => apiDescriptions.First());
})
.EnableSwaggerUi(c =>
{
c.DisableValidator();
});
}
private static bool ResolveVersionSupportByRouteConstraint(ApiDescription apiDesc, string targetApiVersion)
{
if (apiDesc.Route.RouteTemplate.StartsWith("-/api/v1") && targetApiVersion == "my_services") return true;
if (apiDesc.Route.RouteTemplate.StartsWith("sitecore") && targetApiVersion == "sc") return true;
return false;
}
}
}就是这个。它与我们的Sitecore解决方案集成在一起。在他们的网站
我一直在使用Swagger和Sitecore 8.x以及Sitecore 9版本，一切正常！在这里查看我们的GitHub回购
本文参与 腾讯云自媒体同步曝光计划，分享自作者个人站点/博客。 原始发表：2020-06-16，如有侵权请联系 cloudcommunity@tencent 删除解决方案API管理sitecore8swagger工具在Sitecore8.2解决方案中使用Swagger作为API管理工具
假设您的Sitecore解决方案需要一些API服务。显而易见的是使用 Web API实现它们。有时，在构建消费应用程序时，理解API的各种方法对开发人员来说可能是一项挑战。
假设您的Sitecore解决方案需要一些API服务。显而易见的是使用 Web API实现它们。有时，在构建消费应用程序时，理解API的各种方法对开发人员来说可能是一项挑战。Swagger 是RESTful API的机器可读表示， 支持交互式文档，客户端SDK生成和可发现性。
使用Swagger
使用Swagger为Web API生成良好的文档和帮助页面就像添加NuGet包一样简单。
只要Sitecore仍然是一个asp应用程序，我们就可以使用Swagger！所以我实现了一个Web API控制器，我希望在我的Sitecore实例中托管它并以某种方式记录它：
代码语言：javascript代码运行次数：0运行复制namespace Feature.WebApi.Controllers
{
using System.Web.Http;
[RoutePrefix("-/api/v1")]
public class MyServicesApiController : ApiController
{
[HttpGet]
[Route("hello-world")]
public IHttpActionResult HelloWorld()
{
return this.Ok("Hello world");
}
}
}好的，这是我的“hello world”API方法。现在我将使用nuget将Swagger安装到我的Feature.Swagger项目中：
代码语言：javascript代码运行次数：0运行复制install-package Swashbuckle默认的nuget包将在/App_Start/SwaggerConfig.cs中创建启动配置。默认情况下，它使用WebActivator扩展将其绑定到应用程序启动，以便在初始化Web应用程序时执行配置。
默认情况下，它不能与Sitecore平稳运行，但我们可以使用少量配置使其正常工作。Swagger UI的入口点是{your.domain} / swagger。我跑了，看下一张图：
为了解决它，我们需要修改/App_Start/SwaggerConfig.cs并取消注释下一行：
代码语言：javascript代码运行次数：0运行复制c.ResolveConflictingActions(apiDescriptions => apiDescriptions.First());再次运行 - 我们看到下一个问题：
这次我们需要取消注释另一行配置：
代码语言：javascript代码运行次数：0运行复制c.UseFullTypeNameInSchemaIds();好的，现在它已启动并运行，但是底部有一个annoing错误，表示存在架构验证错误。Swagger UI仍然有效，但我们真的不想看到任何错误消息吗？我们可以通过取消另外一行配置来绕过它：
代码语言：javascript代码运行次数：0运行复制c.DisableValidator();Web API服务
现在它查找并运行，我甚至能够找到我的服务方法。但是，Sitecore有很多自己使用的Web API服务，很难找到我自己的服务。将Sitecore本机Web API控制器与我的分离是很好的。它支持API版本控制，从我的角度来看，这是我们如何分离它的方法之一。我们可以向SwaggerConfig添加一个方法，该方法将声明API的版本。
我将Sitecore服务称为版本“ sc ”，将我自己称为“ my_services ”：
代码语言：javascript代码运行次数：0运行复制private static bool ResolveVersionSupportByRouteConstraint(ApiDescription apiDesc, string targetApiVersion)
{
if (apiDesc.Route.RouteTemplate.StartsWith("-/api/v1") && targetApiVersion == "my_services") return true;
if (apiDesc.Route.RouteTemplate.StartsWith("sitecore") && targetApiVersion == "sc") return true;
return false;
}在配置中，我们需要注释/删除此行
代码语言：javascript代码运行次数：0运行复制c.SingleApiVersion("v1", "Feature.Swagger");并添加这个：
代码语言：javascript代码运行次数：0运行复制c.MultipleApiVersions(
ResolveVersionSupportByRouteConstraint,
vc =>
{
vc.Version("my_services", "My services API (you can switch to Sitecore API /swagger/docs/sc)");
vc.Version("sc", "Sitecore services (you can switch to My services API /swagger/docs/my_services)");
});现在我们为Sitecore API和My API提供了2个独立的视图。它们被Swagger UI视为API版本：
安装
或许，公开提供该文档并不是一个好主意，因为它会产生安全问题。因此，我们需要做的是在登录后隐藏Swagger UI，并使其仅供Sitecore管理员用户使用。我们可以重新使用Sitecore的默认登录页面。从我的角度来看，最好的方法是使用HTTP MessageHandlers。我们可以实现下一个消息处理器
代码语言：javascript代码运行次数：0运行复制namespace Feature.Swagger
{
using System;
using System.Net;
using System.Net.Http;
using System.Threading;
using System.Threading.Tasks;
using Sitecore;
public class SwaggerSitecoreAuthMessageHandler : DelegatingHandler
{
protected override Task SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
{
var isAuthenticated = Context.User?.IsAuthenticated ?? false;
var isAdministrator = Context.User?.IsAdministrator ?? false;
if (this.IsSwaggerRequest(request) && (!isAuthenticated || !isAdministrator))
{
var response = new HttpResponseMessage(HttpStatusCode.Redirect);
var uri = request.RequestUri;
var currentOrigin = uri.AbsoluteUri.Replace(uri.PathAndQuery, string.Empty);
var logiPage = currentOrigin + @"/sitecore/login?returnurl=/swagger";
response.Headers.Location = new Uri(logiPage);
return Task.FromResult(response);
}
else
{
return base.SendAsync(request, cancellationToken);
}
}
private bool IsSwaggerRequest(HttpRequestMessage request)
{
return request.RequestUri.PathAndQuery.ToLowerInvariant().StartsWith("/swagger");
}
}
}然后在SwaggerConfig类中添加一行，如下所示：
代码语言：javascript代码运行次数：0运行复制GlobalConfiguration.Configuration.MessageHandlers.Add(new SwaggerSitecoreAuthMessageHandler());现在我们已成功将Swagger安装到Sitecore解决方案中。但是，正如我之前提到的，它使用WebActivator扩展，这更像是Web解决方案的反模式，我最好摆脱它，以保持螺旋原则。相反，我们可以使其更多Sitecore本地方式 - 在Sitecore初始化管道上运行配置。
所以首先我们要做的是删除这一行：
代码语言：javascript代码运行次数：0运行复制[assembly: PreApplicationStartMethod(typeof(SwaggerConfig), "Register")]然后创建一个运行初始化的超简单初始化管道处理器：
代码语言：javascript代码运行次数：0运行复制namespace Feature.Swagger.Pipelines.Initialize
{
using Sitecore.Pipelines;
public class InitializeSwagger
{
public void Process(PipelineArgs args)
{
SwaggerConfig.Register();
}
}
}当然我们需要将它添加到配置文件/App_Config/Include/Feature/Feature.Swagger.config中：
代码语言：javascript代码运行次数：0运行复制<?xml version="1.0" encoding="utf-8" ?>
<configuration xmlns:patch="/" xmlns:set="/">
<sitecore>
<pipelines>
<initialize>
<processor type="Feature.Swagger.Pipelines.Initialize.InitializeSwagger, Feature.Swagger" />
</initialize>
</pipelines>
</sitecore>
</configuration>最后，我的完整SwaggerConfig.cs文件如下所示：
代码语言：javascript代码运行次数：0运行复制namespace Feature.Swagger
{
using System.Web.Http;
using System.Linq;
using Swashbuckle.Application;
using System.Web.Http.Description;
public class SwaggerConfig
{
public static void Register()
{
var thisAssembly = typeof(SwaggerConfig).Assembly;
GlobalConfiguration.Configuration.MessageHandlers.Add(new SwaggerSitecoreAuthMessageHandler());
GlobalConfiguration.Configuration
.EnableSwagger(c =>
{
c.MultipleApiVersions(
ResolveVersionSupportByRouteConstraint,
vc =>
{
vc.Version("my_services", "My services API (you can switch to Sitecore API /swagger/docs/sc)");
vc.Version("sc", "Sitecore services (you can switch to My services API /swagger/docs/my_services)");
});
c.UseFullTypeNameInSchemaIds();
c.ResolveConflictingActions(apiDescriptions => apiDescriptions.First());
})
.EnableSwaggerUi(c =>
{
c.DisableValidator();
});
}
private static bool ResolveVersionSupportByRouteConstraint(ApiDescription apiDesc, string targetApiVersion)
{
if (apiDesc.Route.RouteTemplate.StartsWith("-/api/v1") && targetApiVersion == "my_services") return true;
if (apiDesc.Route.RouteTemplate.StartsWith("sitecore") && targetApiVersion == "sc") return true;
return false;
}
}
}就是这个。它与我们的Sitecore解决方案集成在一起。在他们的网站
我一直在使用Swagger和Sitecore 8.x以及Sitecore 9版本，一切正常！在这里查看我们的GitHub回购
本文参与 腾讯云自媒体同步曝光计划，分享自作者个人站点/博客。 原始发表：2020-06-16，如有侵权请联系 cloudcommunity@tencent 删除解决方案API管理sitecore8swagger工具本文标签： 在Sitecore82解决方案中使用Swagger作为API管理工具
版权声明：本文标题：在Sitecore8.2解决方案中使用Swagger作为API管理工具 内容由热心网友自发贡献，该文观点仅代表作者本人， 转载请联系作者并注明出处：http://it.en369.cn/jiaocheng/1747935019a2230113.html， 本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如发现本站有涉嫌抄袭侵权/违法违规的内容，一经查实，本站将立刻删除。
发表评论