.NET绿叶社区!
返回

.Net Core Swagger使用教程

2020-07-30 .Net Core Swagger 18 0

什么是Swagger?

Swagger是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

Swagger UI允许任何人(无论是您的开发团队还是最终用户)在没有任何实现逻辑的情况下可视化并与API的资源交互。它是根据您的OpenAPI(以前称为Swagger)规范自动生成的,可视化文档使后端实现和客户端使用更加容易。

.Net Core可以通过Nuget轻松安装Swagger组件,使用Swagger UI的强大功能,整个安装过程只需要1分钟,下面跟我来做吧。

Nuget搜索Swashbuckle.AspNetCore安装最新版本。

.Net Core Swagger使用教程

在Startup.cs里注册服务添加Swagger中间件,代码如下

public void ConfigureServices(IServiceCollection services)
{
    // 添加Swagger服务
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "WebApi Swagger", Version = "v1" });
    });
    services.AddControllers();
}
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();
    });
}

到这里,已经安装完成了,直接按F5调试,然后打开http://localhost:{你的端口号}/swagger/index.html即可访问Swagger UI界面了。

我添加了一个示例控制器UserController,里面有Get,Post,Put,Delete四个Action,示例代码如下

namespace WebApiSwagger.Controllers
{
    [Route("api/[controller]")]
    [ApiController]
    public class UserController : ControllerBase
    {
        [HttpGet]
        public string Get(string name) {
            return $"My name is {name}";
        }
        [HttpPost]
        public string Post(string name) {
            return $"Add user {name}";
        }
        [HttpPut]
        public string Put(int id,string name) {
            return $"Update user set name as {name} where id is {id}";
        }
        [HttpDelete]
        public string Delete(string name) {
            return $"Delete {name}";
        }
    }
}

Swagger UI界面如下

.Net Core Swagger使用教程

如图所示,Swagger UI列出了我的接口信息。

.Net Core Swagger使用教程

点击某个接口可以查看接口的参数,如图所示,可以接收一个int类型的id和string类型的name参数。点击Try it out可以直接进行接口调用调试了,连PostMan都省了。

.Net Core Swagger使用教程

如果我们想知道每个方法的注释和方法参数的注释,这就需要对接口做XML注释了。首先安装Microsoft.Extensions.PlatformAbstractions包。

.Net Core Swagger使用教程

然后Startup.cs里Swagger服务增加一下配置

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

右键项目>属性,在生成菜单里勾选XML文档文件,勾选后,后面输入框里会自动显示xml地址,不需要做修改。如果不勾选直接运行会报错。

.Net Core Swagger使用教程

然后直接在接口中添加注释就可以了,还是以我UserController接口为例,我对Put方法做了如下修改,从body接收json格式的内容,输出Json。

[HttpPut]
public object Put([FromBody]UserRequest request) {
    return new
    {
        success = true,
        statusCode = 200,
        message = $"Update user set name as {request.Name} where id is {request.Id}"
    };
}
public class UserRequest { 
    /// <summary>
    /// 用户Id
    /// </summary>
    public int Id { get; set; }
    /// <summary>
    /// 用户姓名
    /// </summary>
    public string Name { get; set; }
}

运行效果如下,注释显示在接口地址后面了,Request也变成application/json类型了,点击Try it out可以修改Body内容进行调试了。

.Net Core Swagger使用教程

调试输出Json格式的结果

.Net Core Swagger使用教程

Swagger更多高级玩法欢迎大家补充。

点赞 收藏

顶部