如何使用 ServiceStack OpenApiFeature/Swagger 与 api 描述和响应示例?
How to use ServiceStack OpenApiFeature/Swagger with api description and response examples?
有没有办法向 api 添加描述(不仅仅是个别路线)并更新 api 版本并使用 Open[=19= 添加示例 responses/resquests ] ServiceStack 中的功能?我在文档中找不到关于这些 swagger ui.
的任何内容
我尝试使用 Api 属性来添加说明,但这似乎不起作用。
唯一的 declarative Attributes that can annotate individual Services 记录在 Open API 文档中。这是一个完整注释的示例:
[Tag("TheTag")]
[Api("SwaggerTest Service Description")]
[ApiResponse(HttpStatusCode.BadRequest, "Your request was not understood")]
[ApiResponse(HttpStatusCode.InternalServerError, "Oops, something broke")]
[Route("/swagger", "GET", Summary = @"GET / Summary", Notes = "GET / Notes")]
[Route("/swagger/{Name}", "GET", Summary = @"GET Summary", Notes = "GET /Name Notes")]
[Route("/swagger/{Name}", "POST", Summary = @"POST Summary", Notes = "POST /Name Notes")]
public class SwaggerExample
{
[ApiMember(Description = "Color Description",
ParameterType = "path", DataType = "string", IsRequired = true)]
[ApiAllowableValues("Name", typeof(MyColor))] //Enum
public string Name { get; set; }
[ApiMember]
[ApiAllowableValues("Color", typeof(MyColor))] //Enum
public MyColor Color { get; set; }
[ApiMember(Description = "Aliased Description", DataType="string", IsRequired=true)]
[DataMember(Name = "Aliased")]
public string Original { get; set; }
[ApiMember(Description = "Not Aliased", DataType="string", IsRequired=true)]
public string NotAliased { get; set; }
[ApiMember(IsRequired = false, AllowMultiple = true)]
public DateTime[] MyDateBetween { get; set; }
[ApiMember(Description = "Nested model 1", DataType = "SwaggerNestedModel")]
public SwaggerNestedModel NestedModel1 { get; set; }
[ApiMember(Description = "Nested model 2", DataType = "SwaggerNestedModel2")]
public SwaggerNestedModel2 NestedModel2 { get; set; }
}
Open API 允许的另一个注释是 grouping logical operations by Tag,您可以在 ServiceStack 中使用带有 [Tag]
属性的注释,然后您可以在注册 [=13] 时提供描述=] 插件,例如:
Plugins.Add(new OpenApiFeature
{
Tags =
{
new OpenApiTag
{
Name = "TheTag",
Description = "TheTag Description",
ExternalDocs = new OpenApiExternalDocumentation
{
Description = "Link to External Docs Desc",
Url = "http://example.org/docs/path",
}
}
}
});
有没有办法向 api 添加描述(不仅仅是个别路线)并更新 api 版本并使用 Open[=19= 添加示例 responses/resquests ] ServiceStack 中的功能?我在文档中找不到关于这些 swagger ui.
的任何内容我尝试使用 Api 属性来添加说明,但这似乎不起作用。
唯一的 declarative Attributes that can annotate individual Services 记录在 Open API 文档中。这是一个完整注释的示例:
[Tag("TheTag")]
[Api("SwaggerTest Service Description")]
[ApiResponse(HttpStatusCode.BadRequest, "Your request was not understood")]
[ApiResponse(HttpStatusCode.InternalServerError, "Oops, something broke")]
[Route("/swagger", "GET", Summary = @"GET / Summary", Notes = "GET / Notes")]
[Route("/swagger/{Name}", "GET", Summary = @"GET Summary", Notes = "GET /Name Notes")]
[Route("/swagger/{Name}", "POST", Summary = @"POST Summary", Notes = "POST /Name Notes")]
public class SwaggerExample
{
[ApiMember(Description = "Color Description",
ParameterType = "path", DataType = "string", IsRequired = true)]
[ApiAllowableValues("Name", typeof(MyColor))] //Enum
public string Name { get; set; }
[ApiMember]
[ApiAllowableValues("Color", typeof(MyColor))] //Enum
public MyColor Color { get; set; }
[ApiMember(Description = "Aliased Description", DataType="string", IsRequired=true)]
[DataMember(Name = "Aliased")]
public string Original { get; set; }
[ApiMember(Description = "Not Aliased", DataType="string", IsRequired=true)]
public string NotAliased { get; set; }
[ApiMember(IsRequired = false, AllowMultiple = true)]
public DateTime[] MyDateBetween { get; set; }
[ApiMember(Description = "Nested model 1", DataType = "SwaggerNestedModel")]
public SwaggerNestedModel NestedModel1 { get; set; }
[ApiMember(Description = "Nested model 2", DataType = "SwaggerNestedModel2")]
public SwaggerNestedModel2 NestedModel2 { get; set; }
}
Open API 允许的另一个注释是 grouping logical operations by Tag,您可以在 ServiceStack 中使用带有 [Tag]
属性的注释,然后您可以在注册 [=13] 时提供描述=] 插件,例如:
Plugins.Add(new OpenApiFeature
{
Tags =
{
new OpenApiTag
{
Name = "TheTag",
Description = "TheTag Description",
ExternalDocs = new OpenApiExternalDocumentation
{
Description = "Link to External Docs Desc",
Url = "http://example.org/docs/path",
}
}
}
});