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 文件的目录

·       请执行以下命令:

Swagger的 ASP.NET Core Web API 帮助页_第1张图片

Swagger的 ASP.NET Core Web API 帮助页_第2张图片

 

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:/swagger/v1/swagger.json。 生成的描述终结点的文档显示在 Swagger 规范 (swagger.json) 中。

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

要在应用的根(http://localhost:/) 处提供 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"注释掉

Swagger的 ASP.NET Core Web API 帮助页_第3张图片


{
  "$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的 ASP.NET Core Web API 帮助页_第4张图片

 

为接口添加注释

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

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

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

Swagger的 ASP.NET Core Web API 帮助页_第5张图片

 

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):

 

最后的运行结果:

 

Swagger的 ASP.NET Core Web API 帮助页_第6张图片

请关注我的微信公众号,我们一起进步:

Swagger的 ASP.NET Core Web API 帮助页_第7张图片

你可能感兴趣的:(DotentCore)