这应该非常简单:
[Route("{organizationSys:int}")]
[ProducesResponseType(typeof(List<Door>), 200)]
[ProducesResponseType(typeof(string), 400)]
public IHttpActionResult Get(int organizationSys)
请注意,由于您有 2 个退出点:一个正常返回数据,以及一个返回错误消息的 catch,因此我在上面的示例中定义了两种可能的结果类型:
- http:200(好的)与
List<Door>
- http:400(BadRequest) 与
string
Swashbuckle Swagger 基础设施将读取该内容并提供很粗糙的这些案例的数据示例。
但是,如果您需要更详细的例子(即具有一些合理的字段值)那么您将必须实现所谓的“示例提供程序”。请参阅此处了解详细信息和快速教程 https://github.com/mattfrear/Swashbuckle.Examples, 简而言之:
[SwaggerRequestExample(typeof(DeliveryOptionsSearchModel), typeof(DeliveryOptionsSearchModelExample))]
public async Task<IHttpActionResult> DeliveryOptionsForAddress(DeliveryOptionsSearchModel search)
and
public class DeliveryOptionsSearchModelExample : IExamplesProvider
{
public object GetExamples()
{
return new DeliveryOptionsSearchModel
{
Lang = "en-GB",
Currency = "GBP",
Address = new AddressModel
{
Address1 = "1 Gwalior Road",
Locality = "London",
Country = "GB",
PostalCode = "SW15 1NP"
},
Items = new[]
{
new ItemModel
{
ItemId = "ABCD",
ItemType = ItemType.Product,
Price = 20,
Quantity = 1,
RestrictedCountries = new[] { "US" }
}
}
};
}
示例提供程序的工作方式非常简单:无论提供程序返回什么,它都会序列化为 JSON 并作为示例返回给定数据类型。就这样。
现在,如果你的方法返回DeliveryOptionsSearchModel
,提供者将直接使用上面的这些数据。
或者,如果您的方法返回一个更大的对象,由DeliveryOptionsSearchModel
如果没有其他提供程序,则 Swagger 会将此提供程序用于响应示例的一部分,并将其他提供程序(或默认的粗略示例)用于大型对象的所有其他部分。
以上所有内容都是针对 Net Core 的。
如果您使用“普通”Net 4.5/4.6/4.7,则此方法不可用,因为 Attribute 类不存在。在 AspMvc for Net 4.x 中只有[ResponseType(typeof(..))]
允许定义单个返回类型的属性。大多数时候都可以。但是,如果您确实需要区分返回类型和响应代码,或者需要提供好的示例,那就是一个问题。
然而!一些好人已经解决了这个问题。看本文 https://mattfrear.com/2015/04/21/generating-swagger-example-responses-with-swashbuckle/。它描述了 NuGetSwagger.Examples
,我相信它是针对非核心的,它的目的是提供更好的结果描述。
它定义了另一个属性 -[SwaggerResponse(HttpStatusCode.OK, Type=typeof(IEnumerable...
定义可能的结果代码和结果类型,并为 Swagger 提供插件来使用该属性。
它还提供了另一个属性,[SwaggerResponseExample...
它允许您定义结果示例提供程序,它可以提供带有数据的自定义良好示例,就像上面针对 Core 描述的 IExampleProvider 一样。整洁的!