ASP.NET Core Swagger

Swagger/OpenAPI 的 ASP.NET Core Web API 帮助页
查看或下载示例代码
Swagger转Word文档
GitHub - Swagger API 文档 转 Word 文档的工具项目

1、管理 NuGet 程序包
     Swashbuckle.AspNetCore
【注意：在添加引用 Swashbuckle.AspNetCore 时，选中“包括预发行版”】

2、包安装

【WebAPI项目】【右键】【属性】

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

public void ConfigureServices(IServiceCollection services)
{
    services.AddDbContext<TodoContext>(opt =>
        opt.UseInMemoryDatabase("TodoList"));

    //services.AddControllers();

    //转换为应用程序
    services.AddControllers(options =>
    {
        //options.UseCentralRoutePrefix(new RouteAttribute($"api")); //普通网站
        options.UseCentralRoutePrefix(new RouteAttribute($""));    //转换为应用程序
    })

    // core 3.0 写法 new OpenApiInfo
    services.AddScoped<SwaggerGenerator>();
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });

        #region 添加方法注释
        var basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);
        var xmlPath = Path.Combine(basePath, "Asset.WebAPI.xml");
        c.IncludeXmlComments(xmlPath, true);

        /// .net6
        var xmlFilename = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
        options.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, xmlFilename), true);

        #endregion

        #region 添加header参数
        var securityScheme = new OpenApiSecurityScheme()
        {
          Description = "JWT Authorization header using the Bearer scheme. Example: \"Authorization: Bearer {token}\"",
          Name = "Authorization",
          In = ParameterLocation.Header,
          Type = SecuritySchemeType.Http,
          Scheme = "bearer",
          BearerFormat = "JWT"
        };
        var securityRequirement = new OpenApiSecurityRequirement
        {
          {
            new OpenApiSecurityScheme{Reference = new OpenApiReference{Type = ReferenceType.SecurityScheme,Id = "bearerAuth"}},
            new string[] {}
          }
        };
        #endregion
    });

    // core 2.2 写法 new Swashbuckle.AspNetCore.Swagger.Info
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new Swashbuckle.AspNetCore.Swagger.Info { Title = "My API", Version = "v1" });
    });
}

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

public void Configure(IApplicationBuilder app)
{
    // Enable middleware to serve generated Swagger as a JSON endpoint.
    app.UseSwagger();

    // Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.),
    // specifying the Swagger JSON endpoint.

#if DEBUG
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
        c.DocumentTitle = "Asset 在线文档调试";
    });
#else
    // 转换为应用程序
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint($"/{Configuration["AppSettings:VirtualPath"]}/swagger/v1/swagger.json", "My API V1");
        c.DocumentTitle = "Asset 在线文档调试";
    });
#endif

    app.UseRouting();
    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
}

5、appsettings.json

  "AppSettings": {
    //"VirtualPath": ""   //普通网站
    "VirtualPath": "Api"  //转换为应用程序
  }

6、添加方法注释说明
选中【Asset.WebAPI】项目，新增【Asset.WebAPI.xml】文件
选中【Asset.WebAPI】项目右键 - 属性 - 生成 - 输出 - XML 文档文件


7、打开 Web 项目文件夹，编辑 WebAPI.csproj 文件

<PropertyGroup>
  <GenerateDocumentationFile>True</GenerateDocumentationFile>
</PropertyGroup>

或 WebAPI\Properties\PublishProfiles\FolderProfile.pubxml 文件

<?xml version="1.0" encoding="utf-8"?>

<Project>
	<PropertyGroup>
		<GenerateDocumentationFile>True</GenerateDocumentationFile>
	</PropertyGroup>
</Project>

8、启动应用
     浏览器输入 http://localhost:<port>/swagger/v1/swagger.json 生成的描述终结点的文档显示。
     浏览器输入 http://localhost:<port>/swagger/index.html 找到 Swagger UI。

9、启动应用（转换为应用程序）
     浏览器输入 http://localhost:<port>/api/swagger/v1/swagger.json 生成的描述终结点的文档显示。
     浏览器输入 http://localhost:<port>/api/swagger/index.html 找到 Swagger UI。

10、IIS目录（转换为应用程序）

*
*
*