到目前为止，我从未真正使用过Swashbuckle / Swagger，因为它似乎不适合我创建真正通用后端的方式。但是我现在想给它一个机会。
我们有多种解决方案，这些解决方案基本上都具有一个API控制器，其外观类似于以下代码（还有其他控制器，但它们要么更简单，要么类似，所以我想一个例子）：
public class DocumentController : ...
{
...
[HttpGet]
public dynamic Get([FromUri]string area, [FromUri]string documentType, [FromUri]Guid id)
{
JObject entity = Lookup(area).Get(id, documentType);
if (entity == null)
{
return NotFound();
}
return entity;
}
[HttpPost]
public dynamic Post([FromUri]string area, [FromUri]string documentType, [FromBody]JObject entity)
{
if (entity == null)
{
return BadRequest("Request did not contain any content.");
}
entity = Lookup(area).Post(documentType, entity);
Hub.Clients.All.post(entity);
return entity;
}
[HttpPut]
public dynamic Put([FromUri]string area, [FromUri]string documentType, [FromUri]Guid id, [FromBody]JObject entity)
{
if (entity == null)
{
return BadRequest("Request did not contain any content.");
}
entity = Lookup(area).Put(id, documentType, entity);
Hub.Clients.All.put(entity);
return entity;
}
[HttpDelete]
public dynamic Delete([FromUri]string area, [FromUri]string documentType, [FromUri]Guid id)
{
JObject deleted = Lookup(area).Delete(id, documentType);
if (deleted == null)
{
return NotFound();
}
Hub.Clients.All.delete(deleted);
return deleted;
}
}
这意味着我们可以做到：
// Post some objects of any kind.
curl -d '{ name:"Kittie", race:"Persian", age: 5 }' -H "Content-Type: application/json" -X POST http://host/api/v1/animals/cat/
curl -d '{ name:"Rafle", race:"Bulldog", age: 10, color: "brown" }' -H "Content-Type: application/json" -X POST http://host/api/v1/animals/dog/
curl -d '{ name:"Bender", race:"Husky", age: 8, color: "white", owner: { name: "Peter", address: "..." } }' -H "Content-Type: application/json" -X POST http://host/api/v1/animals/dog/
curl -d '{ home: "Borneo", race: "proboscis", firstObserved: "1812-01-01T00:00:00Z" }' -H "Content-Type: application/json" -X POST http://host/api/v1/animals/monkey/
// Fetch them again with ID.
curl -X GET --header 'Accept: application/json' 'http://host/api/v1/animals/cat/ce3478b2-0477-4ed1-a6e2-91477926a957'
curl -X GET --header 'Accept: application/json' 'http://host/api/v1/animals/dog/ce3478b2-0477-4ed1-a6e2-91477926a957'
curl -X GET --header 'Accept: application/json' 'http://host/api/v1/animals/dog/affb78b8-80eb-4e50-aead-7e19f32b5867'
curl -X GET --header 'Accept: application/json' 'http://host/api/v1/animals/monkey/e9ab9bbc-c2fc-4069-9edc-f59023d9a46d'
// Computed schemas (Presented here in a "TypeScritesce" form for simplicity, however they are generated as JSON Schemas (https://json-schema.org/) - some caveats apply
cat: { name?: string, race?: string, age?: number }
dog: { name?: string, race?: string, age?: number, color?: string, owner?: object{ name?: string, address?: string } }
monkey: { home?: string, race?: string, firstObserved?: string(datetime) }
虽然架构是自动计算的，所以在本质上，我们可以像猫一样张贴任何东西，但确实会应用验证和权限（可以将权限分解到字段级别），因此架构向用户展示确实有意义这样他们就知道如果希望在文档存储区等中创建Cat对象，可以张贴什么内容。
由于上述内容似乎有些局限，例如，如果您没有ID等，如何找到Cat，因为在所有数据上都有基于Lucene的索引，还有一个Search控制器，它使我们能够对集合中的所有文档进行任意查询。但是现在这与这里无关。
我希望能够广泛了解如何围绕真正的通用数据构建后端。
我的问题是我不太清楚如何使用Swashbuckle以有意义的方式对此进行记录。
捕获端点，例如在文档过滤器中，将PathItems拆分为一个PathItem pr。发现的文档类型。
到目前为止，我已经能够在DocumentFilter中拆分路径项以反映每种文档类型。但是我现在还没有进一步了解它，例如添加对架构等的引用。
总的来说，这似乎是一种糟糕的方法，在使GroupActionsBy等工作时似乎也遇到了一些问题，因为我后来不想这样做了（因为该方法适用于ApiDescriptions而不是路径项）。
这可能也不是拆分PathItem的最佳方法，因为它隐藏了端点是通用的想法，并且具有适当的权限，用户实际上可以发布不是尚未定义。
也许自定义api资源管理器可能是一个更好的选择，但是我刚刚开始研究它，但这听起来确实像是我们需要研究的东西。
我希望对Swashbuckle和/或Swagger更加熟悉的人可以对我如何解决此问题提出一些想法/见解。
如果有人可以为它指出一些巧妙的解决方案，那将是很棒的选择，但是我没有很高的希望，因为我认为以上内容通常可能与ASP.NET WebApis的一般设计和考虑方式完全不同。