自定义自动生成的Swagger定义

如何解决自定义自动生成的Swagger定义

我进行了全面设置，以便在启动时使用NSwag基于WebApi中的控制器生成开放的Api规范和Swagger Ui。我想增强招摇的Ui以便加入

每个端点的摘要/说明
需要终端的示例参数输入
用于POST调用的示例请求正文
一个示例访问令牌，只能在swagger文档中使用，以轻松地进行身份验证并可以尝试所有操作（有点像本示例https://petstore.swagger.io/）

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

我已经阅读了NSwag文档，但这似乎与添加已经配置的ASP.NET Core中间件有关。

编辑： 我现在在页面顶部有一个描述，并且能够在XML注释中添加带有remarks标签的示例- 是否有比使用XML注释更优雅的方法呢？ / strong>

解决方法

页面顶部的说明

要使用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显示如下版本信息：

每个端点的摘要/说明
的示例参数输入
需要它们的端点POST调用的示例请求正文An

只能在招摇中使用的示例访问令牌

文档可轻松进行身份验证并可以尝试所有内容（有点像此示例https://petstore.swagger.io/）

您可以通过在操作标题中添加以下元素来添加说明/示例。

使用<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用户界面现在如下所示：

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

Customize API documentation using NSwag

Customize API info and description using Swashbuckle

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

在线上没有很多文档可以做到这一点（我能找到的只是XML注释方式，所以要花很多时间才能使它起作用）

在这里将我的解决方案发布给不希望使用XML注释弄乱其控制器的其他人。

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

自定义自动生成的Swagger定义

如何解决自定义自动生成的Swagger定义

解决方法

相关推荐