Asp.Net Core集成Swagger及配置

作者 the7
发布于 2020年03月06日
评论 0
浏览 139

Swagger是一个能即时生成在线接口文档,并支持接口调试的Web服务,为程序员带来了极大方便,再也不用改一个字段又去更新文档了。本教程就教你在Asp.Net Core中如何集成Swagger。

安装Swagger

Install-Package Swashbuckle.AspNetCore

Startup.cs中配置

在 startup.cs 文件顶部添加引用

using Microsoft.OpenApi.Models;

ConfigServices 方法里注册Swagger

...
services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
});
...

Configure 方法里使用Swagger

app.UseSwagger();

app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
});

现在点击运行,访问 http://<localhost:port>/swagger/index.html , 如果看到如下图片,表示配置没毛病。

丰富下Swagger UI界面

为swagger ui添加更详细的介绍

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo
    {
        Version = "v1.2",//版本号
        Title = "阎王殿生死簿API",//标题
        Description = "关于阎王殿生死簿相关api,欢迎大家接入", //描述
        TermsOfService = new Uri("https://example.com/terms"),//服务条款
        Contact = new OpenApiContact
        {
            Name = "小鬼",//联系人
            Email = "xiaogui@qq.com",//邮件地址
            Url = new Uri("https://twitter.com/spboyer"),//网址
        },
        License = new OpenApiLicense
        {
            Name = "MIT", //协议
            Url = new Uri("https://example.com/license"),//协议地址
        }
    });
});

现在看起来就是这样了

添加接口注释

注释即每个接口是干什么的,要添加注释这里分小三步。

1. 生成项目xml文件

编辑项目文件 .csproj ,添加如下代码。当然也可以右键操作项目进行可视化操作。

<PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'">
    <DocumentationFile>SwaggerDemo.xml</DocumentationFile>
</PropertyGroup>

2. Startup.cs中修改AddSwaggerGen

services.AddSwaggerGen(c =>
{
    var basePath = AppDomain.CurrentDomain.BaseDirectory;
    var xmlPath = Path.Combine(basePath, "SwaggerDemo.xml");
    c.IncludeXmlComments(xmlPath);
    
    ...
});

3. 在接口方法上添加注释

/// <summary>
/// 获取天气数据
/// </summary>
/// <returns></returns>
[HttpGet]
public IEnumerable<WeatherForecast> Get()
{
    ...
}

现在刷新SwaggerUI,接口上已经有了注释

添加接口备注

有时候一句注释,并不能具体描述接口的方方面面,这时候就可以用到 remarks 了。

// <summary>
/// 创建用户
/// </summary>
/// <remarks>
/// 请求示例:
///
///     POST /Person/Create
///     {
///        "id": 1,
///        "name": "王三",
///        "age": 65,
///        "isAdmin": false
///     }
///
/// 说明:isAdmin只能为false
///
/// </remarks>
/// <param name="person"></param>
/// <returns></returns>
[HttpPost("Create")]
public ActionResult<string> Create(Person person)
{
    return "创建成功";
}

刷新SwaggerUI,就可以看到备注了

添加状态码描述

对于系统的一些异常,可以以状态码返回,如403未授权,这时就可以通过 response 添加一些状态码描述。

/// <summary>
/// 创建用户
/// </summary>
/// <param name="person"></param>
/// <returns></returns>
/// <response code="401">如果未通过认证</response>
/// <response code="400">如果dto为通过验证</response> 
[HttpPost("Create")]
[ProducesResponseType(StatusCodes.Status401Unauthorized)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public ActionResult<string> Create(Person person)
{
    return "创建成功";
}

添加授权验证

当前端在SwaggerUI测试接口时,有些接口是需要授权的,这时可以配置Swagger,让其支持能授权,方便接口调试。

services.AddSwaggerGen(options =>
{
    ...
    c.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme()
    {
        Description = "在下框中输入请求头中需要添加Jwt授权Token:Bearer Token",
        Name = "Authorization",
        In = ParameterLocation.Header,
        Type = SecuritySchemeType.ApiKey,
        BearerFormat = "JWT",
        Scheme = "Bearer"
    });
    c.AddSecurityRequirement(new OpenApiSecurityRequirement
    {
        {
            new OpenApiSecurityScheme
            {
                Reference = new OpenApiReference
                {
                    Type = ReferenceType.SecurityScheme,
                    Id = "Bearer"
                }
            },
            new string[] { }
        }
    });
}

现在SwaggerUI上就有了个Authrize的按钮,如下图所示。点击按钮,输入token既可。

注意:正确格式为 Bearer Token ,中间有个空格哦

4条评论

  • 念往昔丶繁华竞逐

    2019年5月20日

    最后一个五官很漂亮,虽然脸稍微大了一点点,但也算普通人里漂亮的
  • Eleven

    2019年5月20日

    念往昔丶繁华竞逐:
    最后一个五官很漂亮,虽然脸稍微大了一点点,但也算普通人里漂亮的...
    这帖子真的是精品。美中不足的是,为什么要用繁体,虽然能看懂,但有些麻烦呀。
  • SukiU

    2019年5月20日

    我曾在某外企互联网公司工作过一段时间,他们就是那种工作时间聊天摸鱼,下班时间拼命工作,然后加班蹭加班费和补贴😂
微信公众号
站长帮
微信公众号,每日更新!