将请求模式添加到招摇描述答案

【问题标题】：Add request schema to swagger description将请求模式添加到招摇描述
【发布时间】：2021-05-22 06:19:59
【问题描述】：

我正在使用 .Net core 3.1 并致力于在 Swagger 中记录 API 操作，并希望记录请求正文，以便向最终用户显示所有详细信息，例如数据类型、验证等。

目前，我正在对 xml cmets 中的架构进行硬编码，如下所示-

    /// <summary>
    /// Order Details
    /// </summary>
    /// <remarks>
    /// Parameter's description:
    ///
    ///     {
    ///        "productName": string,                           -- Required
    ///        "isUsed: true,                                   
    ///        "orderDate": "2021-02-19T08:43:10.300Z",         -- Required
    ///        "discountDate": "2021-02-19T08:43:10.300Z"
    ///     }       
    /// </remarks>
    /// <returns>Returns Order results</returns>  
    /// <response code="200">Order Placed</response>           
    [HttpPost]
    [Route("Place Order")]
    public ActionResult<OrderPlacingResult> PlaceOrder(OrderPlaceParam orderPlaceParam)
    {
         ///
    }

这给出了预期的结果，对于小型请求体是可行的。但是，如果请求包含大量参数，则不建议在描述部分对其进行硬编码。

谁能建议一种更好的方法来记录参数，以便提供它在架构中提供的所有详细信息。
请注意请求没有实际参数，我想记录请求正文。

【问题讨论】：

你能发布如何在启动configureServices中添加Swagger吗？
@SaeedEsmaeelinejad 我在 configureServices 中使用 AddSwaggerGen

标签： .net-core swagger asp.net-core-webapi swashbuckle.aspnetcore

【解决方案1】：

不应在方法/函数的备注部分中描述参数本身，而应记录请求/响应模型本身（应用summary 标签）。稍后可以在 swagger 文档中找到它。请检查下面的所有屏幕截图，看看它是如何工作的。

附：我故意附上屏幕截图而不是类作为生产代码，对不起。

【讨论】：

【解决方案2】：

Swagger 使用 api 摘要生成文档，如果您不编写这些摘要，则您没有文档。但是您可以避免在代码中编写所有描述并创建 swagger json 并告诉 swagger 使用此文件。当您在启动时添加此行时：

public void ConfigureServices(IServiceCollection services)
        {
            services.AddSwaggerGen(options =>
            {
                //set options
            });
       }
       
 public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        {

            app.UseSwagger();
            app.UseSwaggerUI(c =>
            {
                c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
                c.RoutePrefix = "docs";
                c.DocumentTitle = " Api Title";
            });
         }

您可以在http://localhost:{port}/docs 中查看文档。你也可以在这条路径中看到Swagger生成的json文件：

http://localhost:{port}/swagger/v1/swagger.json

因此，您可以保存此 json 并编辑其中的任何内容，您可以从 api 中删除您的摘要，或者只用几行来描述您的 api，假设您将文件保存在应用程序根目录中，您应该像这样添加它在应用程序中配置：

 app.Map("/swagger/v1/savedfile.json", b =>
                    {
                        b.Run(x =>
                           File.ReadAllTextAsync(Path.Combine(AppContext.BaseDirectory,
                                   "savedfile.json"))
                               .ContinueWith(readTask => x.Response.WriteAsync(readTask.Result))
                            );
                    }).UseSwaggerUI(c =>
                    {
                        c.SwaggerEndpoint("/swagger/v1/savedfile.json", "My API V1");
                        c.RoutePrefix = "docs";
                        c.DocumentTitle = "Api Title";
                    });

【讨论】：