.Net项目使用Swagger

• Swagger简述
• • 项目引用
  • 配置Swagger
  • 生成项目
  • 官方文档：

Swagger简述

Swagger (OpenAPI) 是一个与语言无关的规范，用于描述 REST API。 它使计算机和用户无需直接访问源代码即可了解 REST API 的功能。 
Swagger 项目已于 2015 年捐赠给 OpenAPI 计划，自此它被称为 OpenAPI。 这两个名称可互换使用。 不过，“OpenAPI”指的是规范。 “Swagger”指的是来自使用 OpenAPI 规范的 SmartBear 的开放源代码和商业产品系列。
           

.NET 的两个主要 OpenAPI 实现是 Swashbuckle 和 NSwag

本文章项目使用的是Swashbuckle来进行的操作，NSwag有一系列生成代码的功能，感兴趣的可以去看看官方文档

项目引用

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

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

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

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

没有swaggerGen还需要安装"Swashbuckle.AspNetCore.SwaggerGen"

配置Swagger

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

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers();
        //注册Swagger生成器
            services.AddSwaggerGen(config =>
            {
                config.SwaggerDoc("v1", new OpenApiInfo { Title = "SimpleBlog.WebApi", Version = "v1" });
                // 为 Swagger JSON and UI设置xml文档注释路径
                var basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);//获取应用程序所在目录（绝对，不受工作目录影响，建议采用此方法获取路径）
                var xmlPath = Path.Combine(basePath, "SimpleBlog.xml");//接口action显示注释
                //var xmlPath_entity = Path.Combine(basePath, "实体类库.xml");//分层实体显示注释
                config.IncludeXmlComments(xmlPath);
                //config.IncludeXmlComments(xmlPath_entity);
            });
}
           

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

//使中间件能够将生成的Swagger作为JSON端点。
            app.UseSwagger();
            //使中间件服务于swagger ui
            app.UseSwaggerUI(c =>
              {
                  c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
                  //在应用根目录(localhost:<port>/)处提Swagger UI,根据需求决定
                  c.RoutePrefix = string.Empty;
              });
           

生成项目

启动项目可以在

http://localhost:/swagger/v1/swagger.json 访问swagger文件

http://localhost:/swagger 访问swaggerUI

配置了根目录访问可以直接http://localhost:访问

启动没有访问到json文件可以 在项目上右键–属性–生成–输出–XML文档文件上打√

一个简单的swagger 配置就完成了，更多进阶欢迎大家加群沟通交流

官方文档：

https://docs.microsoft.com/zh-cn/aspnet/core/tutorials/web-api-help-pages-using-swagger?view=aspnetcore-3.1