Asp.Net Core集成Swagger及配置

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

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 ,中间有个空格哦

0条评论

请先登录后发表评论
提交评论
标签云
css (1) less calc (1) C# (4) C#进制转换 (1) asp.net core (8) Authentication (1) 注销 (1) 登录 (1) 验证 (1) scroll-view (1) 微信小程序 (4) 滚动到底部 (1) StackExchange.Redis (1) google (1) 百度 (1) nginx (2) 大文件 (2) 微信小程序c#解密 (1) 微信小程序获取手机号 (1) openid (1) session_key (1) CDN (1) URL鉴权 (1) 阿里云 (1) async (1) await (1) 禁止下拉上滑效果 (1) Index类型 (1) Range类型 (1) dontent publish (1) dotnet publish在线生成器 (1) System.DrawingCore.GDIPlus报错 (1) centos (1) 中文字体 (1) SqlBulkCopy (1) SqlSugar (1) JWT (5) 认证 (3) RSA JWT (1) 非对称加密 (1) 写信 (1) 见字如面 (1) 优化建议 (2) 正确操作字符串 (1) Java (1) JWT退出 (1) RefreshToken (1) .NET Core网站开发框架 (1) Moz (3) 墨子 (1) JSON.NET (1) Newtonsoft (1) System.Text.Json (1) 自定义后台路径 (1) .netcore (1) quartz (2) 作业调度框架 (1) 作业调度 (1) 定时任务 (1) exception (1) 异常处理 (1) HttpClient (1) IHttpClientFactory (1) RDM (1) Redis (1) Redis Desktop Manager (1) RedisDesktopManager (1) linux (1) mac (1) windows (1) Could not get any response (1) postman (1) leetcode (2) 力扣 (1) 回文字符串 (1) 面试刷题 (1) centos7 (1) php安装 (1) 网易云插件 (1) 马甲App (1) Discuz插件 (1) 网易云音乐 (1) Blazor (1) 五子棋 (1) c#解题 (1) 最长连续序列 (1) Swagger (1) 在线文档 (1) blob (1) mp4 (1) 视频 (1) big file (1) 上传 (1) s (1) Azure (1) Azure Key Vault (1) Configuration (1) 密钥保管库 (1) Dapper安装 (1) Dapper是什么 (1) Dapper连接Mysql (1) Dapper连接SqlServer (1) dapper (1)