自定义自动生成的 Swagger 定义

Question

我有 swagger 设置，因此它在项目启动时使用基于我 WebApi 中的控制器的 NSwag 生成开放 Api 规范和 Swagger Ui。我想增强 swagger Ui 以包含

每个端点 summary/description
需要它们的端点的示例参数输入
POST 调用的示例请求正文
一个示例访问令牌，只能在 swagger 文档中使用，以轻松进行身份验证并能够尝试一切（有点像本示例 https://petstore.swagger.io/）

我是 NSwag 的新手，不确定如何将这些增强功能添加到我的代码中，比如在哪里添加它们，我需要使用什么（控制器上的注释？XML 评论？另一种方式？）我试过在 'Swagger Editor' 中编辑规范，但看不出这是怎么回事，因为它会在每次应用程序启动时重新生成。

我已经阅读了 NSwag 文档，但这似乎都是关于添加我已经配置的 ASP.NET 核心中间件。

编辑： 我现在在页面顶部有一个描述，并且已经能够在 XML 评论中添加带有备注标签的示例 - 是否有更优雅的方法这而不是使用 XML 评论？

Answer 1

A description at the top of the page

要使用 Nswag 自定义 API 信息和描述，在 Startup.ConfigureServices 方法中，传递给 AddSwaggerDocument 方法的配置操作会添加作者、许可证和描述等信息：

        services.AddSwaggerDocument(config =>
        {
            config.PostProcess = document =>
            {
                document.Info.Version = "v1";
                document.Info.Title = "ToDo API";
                document.Info.Description = "A simple ASP.NET Core web API";
                document.Info.TermsOfService = "None";
                document.Info.Contact = new NSwag.OpenApiContact
                {
                    Name = "Shayne Boyer",
                    Email = string.Empty,
                    Url = "https://twitter.com/spboyer"
                };
                document.Info.License = new NSwag.OpenApiLicense
                {
                    Name = "Use under LICX",
                    Url = "https://example.com/license"
                };
            };
        });

Swagger UI 显示版本信息如下：

A summary/description for each endpoint Example parameter inputs for

endpoints that require them Example request body for POST calls An

example access token that can be used only in the swagger

documentation to easily authenticate and be able to try everything out (a bit like in this example https://petstore.swagger.io/)

您可以通过向操作 header 添加以下元素来添加 description/example。

使用 <summary> 元素描述端点。

使用 <remarks> 元素补充 <summary> 元素中指定的信息，并提供更强大的 Swagger UI。 <remarks> 元素内容可以由文本、JSON 或 XML 组成。您也可以使用它来添加样本。

使用 <param> 元素添加所需的参数。此外，您还可以将数据注释属性与模型一起使用，它将改变 UI 行为。

使用 <response> 元素描述响应类型。

示例代码如下：

    /// <summary>
    /// Creates a TodoItem.
    /// </summary>
    /// <remarks>
    /// Sample request:
    ///
    ///     POST /Todo
    ///     {
    ///        "id": 1,
    ///        "name": "Item1",
    ///        "isComplete": true
    ///     }
    ///
    /// </remarks>
    /// <param name="todoitem"></param>
    /// <returns>A newly created TodoItem</returns>
    /// <response code="201">Returns the newly created item</response>
    /// <response code="400">If the item is null</response>
    #region snippet_CreateActionAttributes
    [ProducesResponseType(StatusCodes.Status201Created)]     // Created
    [ProducesResponseType(StatusCodes.Status400BadRequest)]  // BadRequest
    #endregion snippet_CreateActionAttributes
    #region snippet_CreateAction
    [HttpPost]
    public ActionResult<TodoItem> Create(TodoItem todoitem)
    {
        _context.TodoItems.Add(todoitem);
        _context.SaveChanges();

        return CreatedAtRoute("GetTodo", new { id = todoitem.Id }, todoitem);
    }

Swagger UI 现在看起来如下：

更多详细信息，请查看以下教程：

Customize API documentation using NSwag

Customize API info and description using Swashbuckle

Answer 2

现在想通了，最终使用操作处理器来配置 Swagger UI/OpenApi 端点摘要、请求示例、路径参数示例值和可能的 UI 响应代码

没有很多在线文档以这种方式进行操作（我所能找到的只是 XML 评论方式，所以这需要大量的试验和错误才能使它工作）

将我的解决方案发布在这里，供其他不希望 XML 评论使他们的控制器混乱的人使用。

将 OpenApiOperationProcessor 属性应用于控制器操作
创建操作处理器并编写 SwaggerUI 自定义代码
路径参数的示例值可以这样填写

自定义自动生成的 Swagger 定义

Customizing auto generated Swagger definitions

swagger-ui

swagger-editor

openapi

asp.net-core-webapi

nswag