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
{

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

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

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

        }

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

        }
    }
}
复制代码

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

 

 在运行程序:

 

 Swagger除了可以显示接口注释以外,还可以进行调试,以前调试都是使用Postman,我们也可以直接使用Swagger进行调试

 

 

这时候是不能输入的,只能查看,点击右上角的“Try it out”:

 

 

 

这样就完成了GET方法的调试。这是无参数方法的调试,如果有参数的方法怎么调试呢?我们以POT方法为例。我们点开POST方法:

 

 

原文地址:https://www.cnblogs.com/dotnet261010/p/12425572.html