ASP.NET Core 3.1使用Swagger API接口文档

2020-12-26 03:29

阅读：727

标签：builder microsoft localhost auth erb 增加 star bho basedir

Swagger是最流行的API开发工具，它遵循了OpenAPI规范，可以根据API接口自动生成在线文档，这样就可以解决文档更新不及时的问题。它可以贯穿于整个API生态，比如API的设计、编写API文档等。而且Swagger还是一种通用的、与具体编程语言无关的API描述规范。

有关更多Swagger的介绍，可以参考Swagger官网，官网地址：https://swagger.io/

1、添加Swagger

直接在NuGet里面搜索Swashbuckle.AspNetCore包进行安装：

技术图片

2、添加服务

在Startup类的ConfigureServices方法里面注入服务：

public void ConfigureServices(IServiceCollection services)
{
    // 添加Swagger
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "API Demo", Version = "v1" });
    });


    services.AddControllers();
}

3、添加中间件

在Startup类的Configure方法里面添加Swagger有关的中间件：

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


    // 添加Swagger有关中间件
    app.UseSwagger();
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "API Demo v1");
    });


    app.UseRouting();

    app.UseAuthorization();

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

4、添加控制器

新建一个控制器，里面包括基础的增删改查方法：

using Microsoft.AspNetCore.Mvc;

namespace SwaggerDemo.Controllers
{
    [Route("api/student")]
    [ApiController]
    public class StudentController : ControllerBase
    {
        [HttpGet]
        public string Get()
        {
            return "Tom";
        }

        [HttpPost]
        public void Post()
        {
            
        }

        [HttpPut]
        public void Put()
        {

        }

        [HttpDelete]
        public void Delete()
        {

        }
    }
}

运行程序，修改一下url地址：

http://localhost:5000/swagger/index.html

技术图片

这样就可以看到接口了。但这样还不是我们最终想要的结果，我们想知道每个方法的注释和方法参数的注释，这就需要对接口做XML注释了。

首先安装Microsoft.Extensions.PlatformAbstractions包：

技术图片

然后修改ConfigureServices方法，增加下面的方法：

public void ConfigureServices(IServiceCollection services)
{
    #region 添加Swagger
    services.AddSwaggerGen(options =>
    {
        options.SwaggerDoc("v1",new  OpenApiInfo { Title = "My API", Version = "v1" });
        // 获取xml文件名
        var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
        // 获取xml文件路径
        var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
        // 添加控制器层注释，true表示显示控制器注释
        options.IncludeXmlComments(xmlPath, true);
    });
    #endregion
    services.AddControllers();
}

然后给新建的接口添加注释：

using Microsoft.AspNetCore.Mvc;

namespace SwaggerDemo.Controllers
{

    /// 
    /// 学生控制器
    /// 
    [Route("api/student")]
    [ApiController]
    public class StudentController : ControllerBase
    {
        /// 
        /// 获取所有学生
        /// 
        /// 
        [HttpGet]
        public string Get()
        {
            return "Tom";
        }

        /// 
        /// 新增学生
        /// 
        [HttpPost]
        public void Post()
        {
            
        }

        /// 
        /// 修改学生信息
        /// 
        [HttpPut]
        public void Put()
        {

        }

        /// 
        /// 删除学生信息
        /// 
        [HttpDelete]
        public void Delete()
        {

        }
    }
}

项目右键，选择属性，勾选“XML文档文件”，如下图所示：

技术图片