Swagger的 ASP.NET Core Web API 帮助页

使用 Web API 时，了解其各种方法对开发人员来说可能是一项挑战。 Swagger 也称为OpenAPI，解决了为 Web API 生成有用文档和帮助页的问题。 它具有诸如交互式文档、客户端 SDK 生成和 API 可发现性等优点。

Swashbuckle 有三个主要组成部分：

1. 1.      Swashbuckle.AspNetCore.Swagger：将 SwaggerDocument 对象公开为 JSON 终结点的 Swagger 对象模型和中间件。

2. 2.      Swashbuckle.AspNetCore.SwaggerGen：从路由、控制器和模型直接生成 SwaggerDocument 对象的 Swagger 生成器。 它通常与 Swagger 终结点中间件结合，以自动公开 Swagger JSON。

3. 3.      Swashbuckle.AspNetCore.SwaggerUI：Swagger UI 工具的嵌入式版本。 它解释 Swagger JSON 以构建描述 Web API 功能的可自定义的丰富体验。 它包括针对公共方法的内置测试工具。

添加Swashbuckle.AspNetCore的方法

1.从“程序包管理器控制台”窗口：

·       转到“视图” > “其他窗口” > “程序包管理器控制台”

·       导航到包含.csproj 文件的目录

·       请执行以下命令：

 

Install-Package Swashbuckle.AspNetCore-Version 5.0.0-rc4

2.从“管理 NuGet 程序包”对话框中：

·       右键单击“解决方案资源管理器” > “管理 NuGet 包”中的项目

·       将“包源”设置为“nuget.org”

·       确保启用“包括预发行版”选项

·       在搜索框中输入“Swashbuckle.AspNetCore”

·       从“浏览”选项卡中选择最新的“Swashbuckle.AspNetCore”包，然后单击“安装”

添加并配置 Swagger 中间件

将 Swagger 生成器添加到 Startup.ConfigureServices 方法中的服务集合中：

public void ConfigureServices(IServiceCollection services)
  {
      services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1);

      services.AddSwaggerGen(c =>
      {
          c.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" });
        
      });
  }

在 Startup.Configure 方法中，启用中间件为生成的 JSON 文档和 Swagger UI 提供服务

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    app.UseSwagger();
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("./swagger/v1/swagger.json", "My API V1");
                  });
    app.UseMvc();
}

启动应用，并导航到 http://localhost:<port>/swagger/v1/swagger.json。 生成的描述终结点的文档显示在 Swagger 规范 (swagger.json) 中。

可在 http://localhost:<port>/swagger 找到 Swagger UI。 通过 Swagger UI 浏览 API，并将其合并其他计划中。

要在应用的根(http://localhost:<port>/) 处提供 Swagger UI，请将RoutePrefix 属性设置为空字符串：

 public void Configure(IApplicationBuilder app, IHostingEnvironment env)
  {
      if (env.IsDevelopment())
      {
          app.UseDeveloperExceptionPage();
      }
      app.UseSwagger();
      app.UseSwaggerUI(c =>
      {
          c.SwaggerEndpoint("./swagger/v1/swagger.json", "My API V1");
          c.RoutePrefix = string.Empty;
      });
      app.UseMvc();
  }

并将launchSettings.json文件中的    "launchUrl": "api/values"注释掉

{
  "$schema": "http://json.schemastore.org/launchsettings.json",
  "iisSettings": {
    "windowsAuthentication": false, 
    "anonymousAuthentication": true, 
    "iisExpress": {
      "applicationUrl": "http://localhost:52655",
      "sslPort": 0
    }
  },
  "profiles": {
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      //"launchUrl": "swagger",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "appDemo": {
      "commandName": "Project",
      "launchBrowser": true,
      //"launchUrl": "swagger",
      "applicationUrl": "http://localhost:5000",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

自定义和扩展

Swagger 提供了为对象模型进行归档和自定义 UI 以匹配你的主题的选项。

API 信息和说明

传递给 AddSwaggerGen 方法的配置操作会添加诸如作者、许可证和说明的信息：

•  
•  
•  
•  
•  
•  
•  
•  
•  
•  
•  
•  
•  
•  
•  
•  
•  
•  
•  
•  
•  
•  
•  
•  
•  
•  
•  
•  

 public void ConfigureServices(IServiceCollection services)        {            services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1);
            services.AddSwaggerGen(c =>            {

                c.SwaggerDoc("v1", new Info                {                    Version = "v1",                    Title = "ToDo API",                    Description = "A simple example ASP.NET Core Web API",                    TermsOfService = "https://blog.csdn.net/zhoubangbang1",                    Contact = new Contact                    {                        Name = "zbb",                        Email = string.Empty,                        Url = "https://blog.csdn.net/zhoubangbang1",                    },                    License = new License                    {                        Name = "Use under LICX",                        Url = "https://blog.csdn.net/zhoubangbang1",                    }                });                          });        }

运行结果：

 

为接口添加注释

将 Swagger 配置为使用按照上述说明生成的 XML 文件。 对于Linux 或非 Windows 操作系统，文件名和路径区分大小写。 例如，“TodoApi.XML”文件在 Windows 上有效，但在 CentOS 上无效。

右键项目名称=>属性=>生成，勾选“输出”下面的“xml文档文件”，系统会默认生成一个，当然老规矩，你也可以自己起一个名字：

这里我用的是相对路径，可以直接生成到 api 层的 bin文件夹下

 

public void ConfigureServices(IServiceCollection services){    services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1);
    services.AddSwaggerGen(c =>    {

        c.SwaggerDoc("v1", new Info        {            Version = "v1",            Title = "ToDo API",            Description = "A simple example ASP.NET Core Web API",            TermsOfService = "https://blog.csdn.net/zhoubangbang1",            Contact = new Contact            {                Name = "zbb",                Email = string.Empty,                Url = "https://blog.csdn.net/zhoubangbang1",            },            License = new License            {                Name = "Use under LICX",                Url = "https://blog.csdn.net/zhoubangbang1",            }        });        //就是这里
        var basePath = PlatformServices.Default.Application.ApplicationBasePath;        var xmlPath = Path.Combine(basePath, " appDemo.xml");//这个就是刚刚配置的xml文件名        c.IncludeXmlComments(xmlPath, true);//默认的第二个参数是false，这个是controller的注释，记得修改                                                });}

 

此时，先别忙着运行项目，会出现很多的警告

这是因为swagger把一些接口方法都通过xml文件配置了。

如果你不想每一个方法都这么加注释，可以这么配置（对当前项目进行配置，可以忽略警告，记得在后边加上分号 ;1591）：

 

最后的运行结果：

 

请关注我的微信公众号，我们一起进步：