我有一个带有简单 REST API 的 aspnet 核心项目。
NSwag 用作 Swagger 工具，它基于我在模型和控制器方法上的装饰工作：
[Route("api/v2/")]
public class JobCollectionsControllerV2 : Controller
{
[HttpPut]
[Route("tenants/{tenant}/collections/{collection}")]
[SwaggerResponse(typeof(JobCollectionDtoV2))]
public async Task<IActionResult> CreateTask(JobCollectionDtoV2 collectionParams)
{
// removed
}
}
public class JobCollectionDtoV2
{
[Required]
[FromRoute]
[RegularExpression("^[a-z][a-z0-9]+$")]
[StringLength(maximumLength: 24, MinimumLength = 3)]
public string Collection { get; set; }
[Required]
[FromRoute]
[RegularExpression("^[a-z][a-z0-9]+$")]
[StringLength(maximumLength: 24, MinimumLength = 3)]
public string Tenant { get; set; }
[Required]
[FromBody]
public JobCollectionDetails CollectionDetails { get; set; }
public override string ToString()
{
return JsonConvert.SerializeObject(this);
}
}
public class JobCollectionDetails
{
[Required]
public bool Enabled { get; set; }
[Required]
[CollectionFrequency]
public TimeSpan Frequency { get; set; }
}
上面的代码使 NSwag 生成以下 Swagger 文件：
{
"put": {
"tags": [
"JobCollectionsControllerV2"
],
"operationId": "JobCollectionsControllerV2_CreateTask",
"parameters": [
{
"type": "string",
"name": "collection",
"in": "path",
"required": true,
"maxLength": 24,
"minLength": 3,
"pattern": "^[a-z][a-z0-9]+$",
"x-nullable": false
},
{
"type": "string",
"name": "tenant",
"in": "path",
"required": true,
"maxLength": 24,
"minLength": 3,
"pattern": "^[a-z][a-z0-9]+$",
"x-nullable": false
},
{
"type": "object",
"name": "collectionDetails",
"in": "query",
"required": true,
"x-schema": {
"$ref": "#/definitions/JobCollectionDetails"
},
"x-nullable": true
}
],
"responses": {
"200": {
"x-nullable": true,
"description": "",
"schema": {
"$ref": "#/definitions/JobCollectionDtoV2"
}
}
}
}
}
看起来很棒，除了以下部分指定collectionDetails应该来自查询参数而不是来自正文。
{
"type": "object",
"name": "collectionDetails",
"in": "query", <<<<-------------- SHOULD BE 'body' or something like that
"required": true,
"x-schema": {
"$ref": "#/definitions/JobCollectionDetails"
},
"x-nullable": true
}
我不确定如何解决这个问题——我非常感谢你在这方面的帮助。
谢谢！
编辑#1（NSwag 初始化）：
public void ConfigureServices(IServiceCollection services)
{
if (_env.IsDevelopment())
{
services.AddMvc();
services.AddSwaggerDocument();
}
}
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
if (env.IsDevelopment())
{
_loggerFactory.AddDebug();
app.UseDeveloperExceptionPage();
app.UseSwagger(settings =>
{
settings.PostProcess = (document, request) =>
{
document.Info.Version = _context.CodePackageActivationContext.CodePackageVersion;
document.Info.TermsOfService = "None";
document.Info.Contact = new SwaggerContact
{
};
};
});
app.UseSwaggerUi3();
}
}