ASP.NET Core WebAPI接口文档

WebAPI接口文档

1、安装Swashbuckle.AspNetCore包

（1）Visual studio 20xx安装，打开程序包管理控制台搜索安装即可

dotnet add package Swashbuckle.AspNetCore --version 6.4.0

（2）Visual studio code安装

Install-Package Swashbuckle.AspNetCore -Version 6.4.0

2、在StartUp中注入依赖（3.1）

ConfigureServices中添加

//注册Swagger生成器，定义一个和多个Swagger 文档
			//using Microsoft.OpenApi.Models;
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v6", new OpenApiInfo
                {
                    Version = "v6",
                    Title = "第一个Asp.Net Core 3.1 WebApi",
                    Description = "一个简单的TestsWebApi测试",
                    TermsOfService = new Uri("https://www.baidu.com"),
                    Contact = new OpenApiContact
                    {
                        Name = "璀璨的疯子",
                        Email = "1024@qq.com",
                        Url = new Uri("https://www.baidu.com")
                    },
                    License = new OpenApiLicense
                    {
                        Name = "璀璨的疯子",
                        Url = new Uri("https://www.baidu.com")
                    }
                });
            });
 			//添加跨域访问
            services.AddCors(options =>
            {
                options.AddPolicy("AllowAll", builder =>
                {
                    builder
                    .AllowAnyOrigin()
                    .AllowAnyMethod()
                    .AllowAnyHeader()
                    //添加之后才可以从服务器段返回自定义的Headers
                    .WithExposedHeaders("X-Pagination");
                });
            });

Configure中添加

//添加跨域访问，一定要在UseHttpsRedirection之前
app.UseCors("AllowAll");

添加在最后或者添加在 if (env.IsDevelopment())中

//启用中间件服务生成Swagger作为JSON终结点
app.UseSwagger();
//启用中间件服务对swagger-ui，指定Swagger JSON终结点
//这里的v6与上面ConfigureServices的v6对应
app.UseSwaggerUI(c =>
{
 	c.SwaggerEndpoint("/swagger/v6/swagger.json", "Test Api V6");
	//添加这个以后网页访问Api就不需要加上/swagger,直接使用index.html即可
	c.RoutePrefix = string.Empty;
});

3、在Program中添加依赖注入（.net6）

builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v6", new OpenApiInfo
    {
        Version = "v6",
        Title = "第一个Asp.Net Core 3.1 WebApi",
        Description = "一个简单的TestsWebApi测试",
        TermsOfService = new Uri("https://www.baidu.com"),
        Contact = new OpenApiContact
        {
            Name = "璀璨的疯子",
            Email = "1024@qq.com",
            Url = new Uri("https://www.baidu.com")
        },
        License = new OpenApiLicense
        {
            Name = "璀璨的疯子",
            Url = new Uri("https://www.baidu.com")
        }
    });
});
//跨域访问
builder.Services.AddCors(options =>
{
    options.AddPolicy("AllowAll", builder =>
    {
        builder
            //限制请求
            .WithOrigins(new string[] {"https://localhost:5001","http://localhost:5000","http://localhost:5173" })
        .WithMethods(new string[] {"GET","POST", "OPTIONS" })
        //.AllowAnyOrigin()//任意地址
        //.AllowAnyMethod()//任意方法
        .AllowAnyHeader();//任意头
        //添加之后才可以从服务器段返回自定义的Headers
        //.WithExposedHeaders("X-Pagination");
    });
});

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI(c =>
{
 	c.SwaggerEndpoint("/swagger/v6/swagger.json", "Test Api V6");
	//添加这个以后网页访问Api就不需要加上/swagger,直接使用index.html即可
	c.RoutePrefix = string.Empty;
});
}
//添加跨域访问，一定要在UseHttpsRedirection之前
app.UseCors("AllowAll");

4、显示接口说明

在xxxx.csproj中添加如下代码，添加的主要是PropertyGroup里面的内容，如果PropertyGroup里面内容则在下面添加即可

  <PropertyGroup>
    <!--原有的内容-->
    <TargetFramework>netcoreapp6.0</TargetFramework>
      <!--新添加的内容-->
	<GenerateDocumentationFile>true</GenerateDocumentationFile>
	  <NoWarn>$(NoWarn);1591</NoWarn>
  </PropertyGroup>

在services.AddSwaggerGen中添加如下代码

// using System.Reflection;
var xmlFilename = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
c.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, xmlFilename));

在xxxDbContext中添加如下#后面的代码

	#pragma warning disable CS1591
    public partial class YangWebApiContext : DbContext
    {
    ...........
    }
    #pragma warning disable CS1591

然后接口上的summary中的内容就显示在接口上了