【.Net Core从零开始前后端分离】（三）—— 接口文档工具Swagger集成

前言

今天学习swagger，它是一款让你更好的书写API文档的框架。

这篇文章主要是转载《从壹开始前后端分离【.NET Core2.0/3.0 +Vue2.0 】框架之三 || Swagger的使用 3.1》。

配置Swagger服务

1、利用NuGet包添加程序集应用，引用Nuget包

右键项目中的依赖 -- > 管理 Nuget程序包 --> 浏览 --> 搜索 "Swashbuckle.AspNetCore" --> 右边就会出现安装的按钮，安装即可

然后就在项目的依赖项-包里看到刚刚引入的Swagger包

2、配置服务

打开Startup.cs类，编辑 ConfigureServices 类

 //设置全局变量
 public string ApiName { get; set; } = "Blog.Core";
 public void ConfigureServices(IServiceCollection services)
    {
        services.AddControllers();

        var basePath = AppContext.BaseDirectory;
        services.AddSwaggerGen(c =>
        {
            c.SwaggerDoc("V1", new OpenApiInfo
            {
                // {ApiName} 定义成全局变量，方便修改
                Version = "V1",
                Title = $"{ApiName} 接口文档——Netcore 3.1",
                Description = $"{ApiName} HTTP API V1",
             });
            c.OrderActionsBy(o => o.RelativePath)；
        });
    }

3、启动Http中间件

编辑Configure类

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }

        app.UseSwagger();
        app.UseSwaggerUI(c =>
        {
            c.SwaggerEndpoint($"/swagger/V1/swagger.json", $"{ApiName} V1");

            //原来的访问地址localhost:5000/swagger，如果想在根域名（localhost:5000）访问该文件，可以配置下面代码
             //路径配置为空，表示直接在根域名（localhost:5000）访问该文件,然后在launchSettings.json文件把launchUrl去掉，如果你想换一个路径，直接写名字即可，比如直接写c.RoutePrefix = "doc";
             c.RoutePrefix = "";
        });

        app.UseRouting();

        app.UseAuthorization();

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

把launchSettings.json文件把launchUrl去掉或者设置为空

4、查看效果

5、为接口添加注释

右键项目名称=>属性=>生成，勾选“输出”下面的“xml文档文件”，系统会默认生成一个，当然老规矩，你也可以自己起一个名字：

运行一下项目，发现会有很多警告

是因为swagger把一些接口方法都通过xml文件配置了，就是刚刚上文提到的，所以我们只需要加上方法注释就可以辣，可以左斜杠/，连续三下即控制器也可加注释

如果你不想每一个方法都这么加注释，可以这么配置（对当前项目进行配置，可以忽略警告，记得在后边加上分号 ;1591）：

现在呢，配置好了xml文件，接下来需要让系统启动的时候，去读取这个文件了，重新编辑Startup.cs，修改ConfigureServices函数，注意配置的参数 true：

    public string ApiName { get; set; } = "Blog.Core";

    // This method gets called by the runtime. Use this method to add services to the container.
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddControllers();

        var basePath = AppContext.BaseDirectory;
        services.AddSwaggerGen(c =>
        {
            c.SwaggerDoc("V1", new OpenApiInfo
            {
                // {ApiName} 定义成全局变量，方便修改
                Version = "V1",
                Title = $"{ApiName} 接口文档——Netcore 3.1",
                Description = $"{ApiName} HTTP API V1",
             });
            c.OrderActionsBy(o => o.RelativePath);

            //就是这里！！！！！！！！！
            var xmlPath = Path.Combine(basePath, "Blog.Core.API.xml");//这个就是刚刚配置的xml文件名
            c.IncludeXmlComments(xmlPath, true);//默认的第二个参数是false，这个是controller的注释，记得修改
        });
    }

然后F5 运行，都加上了

6、对 Model也添加注释说明

新建一个.net core 类库Blog.Core.Model

新建一个Love的实体类

/// <summary>
/// 这是爱
/// </summary>
public class Love
{
    /// <summary>
    /// id
    /// </summary>
    public int Id { get; set; }
    /// <summary>
    /// 姓名
    /// </summary>
    public string Name { get; set; }
    /// <summary>
    /// 年龄
    /// </summary>
    public int Age { get; set; }
}

当前 API 层直接引用了 Blog.Core.Model 层；

这个时候，我们只需要配置仿照上边 api 层配置的xml文档那样，在 Blog.Core.Model 层的 XML 输出到 API 层就行了：

7、改写注入方法，并在控制器中参数引用

配置xml文档，在 startup.cs 的 configureService 方法里

//就是这里
var xmlPath = Path.Combine(basePath, "Blog.Core.xml");//这个就是刚刚配置的xml文件名
c.IncludeXmlComments(xmlPath, true);//默认的第二个参数是false，这个是controller的注释，记得修改

var xmlModelPath = Path.Combine(basePath, "Blog.Core.Model.xml");//这个就是Model层的xml文件名
c.IncludeXmlComments(xmlModelPath);

WeatherForecastController控制器新增接口，并且添加注释