asp.net-core-webapi - 自定义自动生成的 Swagger 定义

Question

我有 swagger 设置，以便它在项目启动时使用 NSwag 基于我的 WebApi 中的 Controller 生成开放的 Api 规范和 Swagger Ui。
我想增强招摇的 Ui 以包括

每个端点的摘要/描述

需要它们的端点的示例参数输入

POST 调用的示例请求正文

一个示例访问 token ，只能在 swagger 文档中使用，以轻松进行身份验证并能够尝试所有内容(有点像本示例中的 https://petstore.swagger.io/)

我是 NSwag 的新手，不确定如何将这些增强功能添加到我的代码中，比如在哪里添加它们，我需要使用什么( Controller 上的注释？XML 注释？另一种方式？)我试过在 ' 中编辑规范Swagger Editor”，但不知道这是怎么回事，因为它会在每次应用程序启动时重新生成。
我已经阅读了 NSwag 文档，但这似乎是关于添加我已经配置的 ASP.NET Core 中间件。
编辑:
我现在在页面顶部有一个描述，并且已经能够在 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/)

您可以通过将以下元素添加到操作标题来添加描述/示例。
使用 <summary>元素来描述端点。
使用 <remarks>元素来补充 <summary> 中指定的信息元素并提供更强大的 Swagger UI。 <remarks>元素内容可以由文本、JSON 或 XML 组成。您也可以使用它来添加示例。
使用 <param>元素添加所需的参数。此外，您还可以将 Data annotations 属性与 Model 一起使用，它会改变 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