我在 .NET Core 3.1 项目中使用 Swashbuckle 和 Swagger UI,并将我的 XML 注释导入 Swagger。我在控制器上有一个 POST 请求,我想在 Swagger 中注册多个响应状态(201、401、403、404)。问题是我还看到一个200 Successswagger.json
响应与我在文件和 Swagger UI 界面中明确指定的状态代码响应一起列出。
正如在多个不同的地方所建议的那样,我正在使用该[SwaggerResponseRemoveDefaults]
属性来尝试防止这种情况发生,但是我尝试的所有操作仍然会导致列出默认的 200 响应。
我试过了:
- 将属性添加到方法中,
- 将属性添加到控制器,
- 将属性添加到抽象基本控制器,
以及以上的所有组合。我还结合以下方法尝试了这些:
<response code="XXX"></response>
使用 XML注释标签指定所需的响应类型,以及[SwaggerResponse(XXX)]
使用端点指定所需的响应类型。
从我的 Swagger UI和swagger.json
.
TrackerController.cs
/// <summary>...</summary>
/// <response code="401">User is not authenticated.</response>
/// <response code="404">Tracker not found.</response>
[Authorize]
[ApiController]
[Route("[controller]")]
[SwaggerResponseRemoveDefaults]
public partial class TrackersController : AbstractController
{
...
/// <summary>...</summary>
/// <param name="tracker">The details of the tracker to be created.</param>
/// <response code="201">The tracker was successfully created.</response>
/// <response code="403">User is not authorized to modify this resource.</response>
[HttpPost]
[SwaggerResponseRemoveDefaults]
[ResponseType(typeof(TrackerDto))]
[SwaggerResponse(201, Description = "The tracker was successfully created.")]
public async Task<IActionResult> CreateTracker([FromBody] TrackerDto tracker)
{
...
}
...
}
招摇.json
{
"openapi": "3.0.1",
"info": {
"title": "My API",
"version": "v1"
},
"paths": {
"/Trackers": {
"post": {
"tags": [
"Trackers"
],
"summary": "Create a new tracker.",
"requestBody": {
"description": "The details of the tracker to be created.",
"content": {
"application/json-patch+json": {
"schema": {
"$ref": "#/components/schemas/TrackerDto"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/TrackerDto"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/TrackerDto"
}
},
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/TrackerDto"
}
}
}
},
"responses": {
"200": {
"description": "Success"
},
"201": {
"description": "The tracker was successfully created."
},
"401": {
"description": "User is not authenticated."
},
"403": {
"description": "User is not authorized to modify this resource."
},
"404": {
"description": "Tracker not found."
}
}
}
}
}
}