Asp.net core WebApi 使用Swagger生成帮助页实例

欢迎您使用 Asp.net core WebApi 来创建 Web 应用程序。Swagger是一个流行的API文档工具，它可以根据代码中的注释生成API的帮助文档。在本文中，我将向您演示如何将Swagger集成到Asp.net core WebApi中，以便快速生成API的帮助文档。

安装 Swagger

首先，您需要在您的项目中安装 Swagger。您可以通过使用 NuGet 包管理器安装 Swagger。打开 NuGet 包控制台，并运行以下命令：

Install-Package Swashbuckle.AspNetCore

配置 Swagger

安装完 Swashbuckle.AspNetCore 后，在 Startup.cs 文件的 ConfigureServices 方法中添加 Swagger 配置。在使用 Swagger 的过程中我们需要使用 SwaggerGen 和 SwaggerUI 两个中间件。

using Microsoft.OpenApi.Models;
using Swashbuckle.AspNetCore.SwaggerGen;
using Swashbuckle.AspNetCore.SwaggerUI;

// ...
public void ConfigureServices(IServiceCollection services)
{
    // ...
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
    });

    services.AddSwaggerGenNewtonsoftSupport();
    // ...
}

在 Configure 方法中，配置 SwaggerUI：

app.UseSwagger();
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    c.RoutePrefix = string.Empty;
});

Swagger的UI界面现在应该可以通过访问 https://localhost:5001/swagger/index.html 来进行查看。

添加注释

您应该已经设置了 Swagger 的基本配置并且可以查看 SwaggerUI 的页面了。现在，我们需要告诉 Swagger 我们要生成我们API文档的哪些部分。要实现这一点，我们可以在 WebApi 控制器和操作方法上添加注释。

[ApiController]
[Route("[controller]")]
public class WeatherForecastController : ControllerBase
{
    /// <summary>
    /// 获取天气预报
    /// </summary>
    /// <returns>返回天气预报</returns>
    [HttpGet]
    public IEnumerable<WeatherForecast> Get()
    {
        // ...
    }
}

在上面的代码中，您可以看到，我们已经添加了一个注释来描述 Get 方法的作用。这种注释是用来描述 API 文档的，Swagger 会将这个注释转换为可读的文档。

配置 Swagger

上面的代码中，我们已经告诉Swashbuckle.AspNetCore要生成我们API文档的哪些部分。安装完成注释后，接下来我们就可以生成API帮助文档了。在编译好我们的WebAPI后，Swagger会自动生成一个json文件以供我们查看或者编辑。

我们可以在 https://localhost:5001/swagger/v1/swagger.json 中查看该json文件内容。在这个文件中，Swagger描述了我们API的结构、文档、参数、返回结果等详细信息。

此外，我们也可以手动修改这个json文件，比如给添加一些缺失的参数描述，或者从Swagger中去除一些不必要的描述。

使用示例

示例1：获取天气预报

下面的代码演示了如何使用C# HttpClient来调用我们的API。

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;

namespace ConsoleApp1
{
    class Program
    {
        static readonly HttpClient client = new HttpClient();
        static async Task Main(string[] args)
        {
            client.BaseAddress = new Uri("https://localhost:5001");
            client.DefaultRequestHeaders.Accept.Clear();
            client.DefaultRequestHeaders.Accept.Add(
                new MediaTypeWithQualityHeaderValue("application/json"));

            var response = await client.GetAsync("weatherforecast");
            if (response.IsSuccessStatusCode)
            {
                var data = await response.Content.ReadAsStringAsync();
                Console.WriteLine(data);
            }
        }
    }
}

示例2：使用curl调用API

在命令行中，使用curl来调用GET操作，可以得到天气预报的JSON数据。

curl https://localhost:5001/weatherforecast

以上就是整个如何实现 Asp.net core WebApi 使用 Swagger 生成帮助页的详细攻略，包括Swagger的安装，配置，注释以及示例说明。