使用基于命名空间的ApiControllers定制ApiExplorer

Question

我正在尝试在我的后端系统中添加API文档.默认的ApiExplorer和帮助页面工作非常好,直到我向Api控制器引入版本.

为了添加版本,我在Controllers文件夹下创建了子文件夹:

• V1
• V2
• V3

并在那里有基于版本的Api控制器.为了让我的Api可被发现,我必须重写DefaultHttpControllerSelector以考虑任何客户端提供的命名空间并将它们映射到右侧控制器:

• http://backend.com/api/v1/controller/action
• http://backend.com/api/v2/controller/action

这打破了我的默认ApiExplorer,以下属性返回ZERO api描述

Configuration.Services.GetApiExplorer().ApiDescriptions

如何自定义现有的ApiExplorer并帮助他找到我的Api控制器,而不是重写整个ApiExplorer实现.我真的只需要显示在哪里找到我的Api控制器.

请指教.

Answer 1

我会告诉你一种方法.此代码仅供学习.在这里,我不是在谈论设计和最佳实践,所以随时随地改变你想要的东西.

那么,你必须遵循以下步骤:

1)创建自定义ApiExplorer:

public class MyApiExplorer: ApiExplorer
{
    private readonly string _version;

    public MyApiExplorer(string version) : base(GlobalConfiguration.Configuration)
    {
        _version = version != null ? version.ToUpperInvariant() : "V1";

        foreach(var apiDescription in ApiDescriptions)
        {
            apiDescription.RelativePath = apiDescription.RelativePath.Replace("{version}", _version);
        }

    }

    public override bool ShouldExploreController(string controllerVariableValue, HttpControllerDescriptor controllerDescriptor,
        IHttpRoute route)
    {
        return controllerDescriptor.ControllerType.FullName.Contains(_version);
    }

}

a)在构造函数中,_version将转换为upperCase(以防它将作为lowerCase传递),但如果它为null,则它将默认为V1.然后更改相对路径以显示特定版本而不是{version}.

b)ShouldExploreController(简言之)决定是否采用特定控制器在文档中显示.在这种情况下,我们只显示控制器,其类型全名包含选择的版本.

2)转到HelpController类并更改Index方法,如下所示:

public ActionResult Index(string version)
{
    //...

    Configuration.Services.Replace(typeof(IApiExplorer), new MyApiExplorer(version));

    return View(Configuration.Services.GetApiExplorer().ApiDescriptions);
}

我们正在替换当前的ApiExplorer,以便在调用Configuration.Services.GetApiExplorer()时返回

现在您可以使用此.../help？version = v1或.../help？version = v2或.../help？version = v3,您将获得特定的api控制器文档.

Answer 2

原来这与ApiExplorer无关.相反,您应该修改基于命名空间的控制器选择器:

NamespaceHttpControllerSelector : DefaultHttpControllerSelector
{
//...
    public override IDictionary<string, HttpControllerDescriptor> GetControllerMapping() 
    {
        var mapping = base.GetControllerMapping();
        mapping["User"] = new HttpControllerDescriptor
        {
            Configuration = _httpConfig,
            ControllerName = "User",
            ControllerType = typeof(UserController)
        };
        //...
        return mapping;
    }
    //...  }

那是.在此默认情况下,ApiExplorer将找到您的控制器并获取所有操作.