最近教程请参考：Swashbuckle 和 ASP.NET Core 入门

Swagger 用于自动生成 API 文档。此教程基于微软官方的 Todo API，你也可以基于其他 ASP.NET Core Web API 程序。

安装包

  1. 打开程序包管理器控制台

  2. Install-Package Swashbuckle.AspNetCore

PS：也可以在“管理 NuGet 包” 中搜索安装。

添加并配置 Swagger 中间件

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

  1. public void ConfigureServices(IServiceCollection services)
  2. {
  3.     services.AddDbContext<TodoContext>(opt =>
  4.         opt.UseInMemoryDatabase("TodoList"));
  6.     services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1);
  8.     // Register the Swagger generator, defining 1 or more Swagger documents
  9.     services.AddSwaggerGen(c =>
  10.     {
  11.         c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
  12.     });
  13. }

引用命名空间：

  1. using Microsoft.OpenApi.Models;

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

  1. public void Configure(IApplicationBuilder app)
  2. {
  3.     app.UseDefaultFiles();
  4.     app.UseStaticFiles();
  6.     // Enable middleware to serve generated Swagger as a JSON endpoint.
  7.     app.UseSwagger();
  9.     // Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.), 
  10.     // specifying the Swagger JSON endpoint.
  11.     app.UseSwaggerUI(c =>
  12.     {
  13.         c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
  14.     });
  16.     app.UseMvc();
  17. }

在 http://localhost:/swagger/v1/swagger.json 中查看生成的 JSON：
Swagger 自动生成 API 文档 - 图1

在 http://localhost:/swagger 查看 Swagger UI：
Swagger 自动生成 API 文档 - 图2

自定义和扩展

配置信息

通过 AddSwaggerGen 方法配置作者、许可证和说明等信息：

  1. // Register the Swagger generator, defining 1 or more Swagger documents
  2. services.AddSwaggerGen(c =>
  3. {
  4.     c.SwaggerDoc("v1", new Info
  5.     {
  6.         Version = "v1",
  7.         Title = "ToDo API",
  8.         Description = "A simple example ASP.NET Core Web API",
  9.         TermsOfService = "None",
  10.         Contact = new Contact
  11.         {
  12.             Name = "Name xx",
  13.             Email = "xx@xx.com",
  14.             Url = "https://www.yuque.com/yuejiangliu/everydaydotnet"
  15.         },
  16.         License = new License
  17.         {
  18.             Name = "Use under LICX",
  19.             Url = "https://example.com/license"
  20.         }
  21.     });
  22. });

效果：
image.png

自定义 UI

  1. 在 Configure 方法中启用静态文件中间件

    1. app.UseStaticFiles();

  2. 前往 Swagger UI GitHub 获取 dist 文件夹的内容

  3. 创建 wwwroot/swagger/ui 文件夹，然后将 dist 文件夹的内容复制到其中

  4. 在 wwwroot/swagger/ui 中创建 custom.css

    1. .swagger-ui .topbar {
    2.  background-color: #000;
    3.  border-bottom: 3px solid #547f00;
    4. }

  5. 在 index.html 中引用 custom.css

    1. <link href="https://fonts.googleapis.com/css?family=Open+Sans:400,700|Source+Code+Pro:300,600|Titillium+Web:400,600,700" rel="stylesheet">
    2. <link rel="stylesheet" type="text/css" href="./swagger-ui.css">
    3. <link rel="stylesheet" type="text/css" href="custom.css">

效果：
Swagger 自动生成 API 文档 - 图4

PS：更多有关自定义 Swagger 请参考 Docs，它们包括：

  • XML 注释

  • 数据注释

  • 描述响应类型