OpenAPI(Swagger)

两者可互换使用，OpenAPI一般指规范，Swagger一般指使用OpenAPI规范的工具（实现），如Swashbuckle,NSwag就是.NET的两个主要OpenAPI实现。

Swashbuckle使用

基本使用

1. 安装三个组件

   • Swashbuckle.AspNetCore.Swagger
   • Swashbuckle.AspNetCore.SwaggerGen
   • Swashbuckle.AspNetCore.SwaggerUI

2. 注册Swagger生成器服务

   • builder.Services.AddSwaggerGen();

3. 配置Swagger中间件

   • app.UseSwagger();
   • app.UseSwaggerUI();

4. 添加成功

   • 展示SwaggerUI
   • http://localhost:5150/swagger
   • 展示OpenAPI规范
   • http://localhost:5150/swagger/v1/swagger.json

自定义

1. launchUrl 设置起始页为swaggerUI

  "profiles": {
    "NET6WebAPINew2": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "launchUrl": "swagger",
      "applicationUrl": "http://localhost:5150",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "launchUrl": "swagger",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }

2. 修改描述信息

builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new OpenApiInfo
    {
        // 版本
        Version = "v1",
        // 标题
        Title = "ToDo API",
        // 标题描述
        Description = "An ASP.NET Core Web API for managing ToDo items",
        // 
        TermsOfService = new Uri("https://example.com/terms"),
        // 联系方式
        Contact = new OpenApiContact
        {
            Name = "Example Contact",
            Email = "123@163.com",
            Url = new Uri("https://example.com/contact")
        },
        // 证书
        License = new OpenApiLicense
        {
            Name = "Example License",
            Url = new Uri("https://example.com/license")
        }
    });
});

3. （没搞懂）

app.UseSwagger(options =>
{
    options.SerializeAsV2 = true;
});

app.UseSwaggerUI(options => 
{
  options.SwaggerEndpoint("/swagger/v1/swagger.json", "v1"); 
  // 路由前缀默认为swagger，因为赋初值为swagger，
  options.RoutePrefix = string.Empty;
  // 可如下加前缀
  // options.RoutePrefix = "swagger/api";
});

4. 添加XML注释

builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new OpenApiInfo
    {
        // 版本
        Version = "v1",
        // 标题
        Title = "ToDo API",
        // 标题描述
        Description = "An ASP.NET Core Web API for managing ToDo items",
        // 
        TermsOfService = new Uri("https://example.com/terms"),
        // 联系方式
        Contact = new OpenApiContact
        {
            Name = "Example Contact",
            Email = "123@163.com",
            Url = new Uri("https://example.com/contact")
        },
        // 证书
        License = new OpenApiLicense
        {
            Name = "Example License",
            Url = new Uri("https://example.com/license")
        }
    });
    options.IncludeXmlComments(AppContext.BaseDirectory+Assembly.GetExecutingAssembly().GetName().Name+".xml",true);
});

• 同时，在属性中开启生成XML注释（包含API文档的注释），之后重新编译

5. 自定义UI
   • 引入IGeekFan.AspNetCore.Knife4jUI组件
   • 使用

   app.UseKnife4UI(options => 
   {
     options.SwaggerEndpoint("/swagger/v1/swagger.json", "v1"); 
     // 路由前缀默认为swagger，因为赋初值为swagger，
     options.RoutePrefix = string.Empty;
   });