api - 使用 Swagger 和 ServiceStack 记录响应类

Question

在 petstore example他们从 wordnik 提供了其响应类的文档。在/pet/{petId} 端点上可以看到一个示例:

Pet {
    name (string, optional),
    id (integer, optional): foo,
    category (Category, optional),
    photoUrls (array[string], optional),
    tags (array[Tag], optional),
    status (string, optional) = ['available' or 'pending' or 'sold']: pet status in the store
}

看起来它支持以下参数:

• 可选(指定属性是否始终位于响应中的标志)
• 允许的值
• 描述

有没有办法通过 ServiceStack 实现来实现这一点？

Answer 1

以下是自 3.9.59 版本起 ServiceStack Swagger 实现当前支持的内容:

• 可选:仅可空值类型被描述为可选。除此之外，目前不支持显式定义请求/响应正文中的哪些属性是可选的。对于路径或查询字符串参数，您可以使用 ApiMemberAttribute 控制可选性
• 允许值:枚举类型将自动获取允许值的列表。对于其他类型(例如具有一组预定义值的 string 属性)，请使用 ApiAllowableValues 注释该属性属性
• 描述:使用System.ComponentModel.Description属性

确保您的请求 DTO 实现 IReturn<ResponseDtoType>界面。

考虑到当前的 ServiceStack Swagger 实现，以下可能是我能想到的与 Petstore 示例最接近的近似值:

public class Pet
{
    public string Name { get; set; }
    [Description("foo")]
    public int? Id { get; set; }
    public Category Category { get; set; }
    public List<string> PhotoUrls { get; set; }
    public List<Tag> Tags { get; set; }

    // If "Status" is implemented internally as a string
    [Description("pet status in the store")]
    [ApiAllowableValues("Status", "available", "pending", "sold")]
    public string Status1 { get; set; }

    // If you can implement "Status" as an enum, the allowable values
    // are instead automatically documented:
    [Description("pet status in the store")]
    public Statuses Status2 { get; set; }

    public enum Statuses { available, pending, sold }
}

该 DTO 中唯一被标记为可选的属性是 Id .