asp.net core swagger使用及注意事项
Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。是一款RESTFUL接口的文档在线自动生成+功能测试软件。主要目的是构建标准的、稳定的、可重用的、交互式的API以及简单方便的功能测试。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。Swagger 让部署管
Swagger
是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful
风格的 Web 服务。是一款RESTFUL
接口的文档在线自动生成+功能测试软件。主要目的是构建标准的、稳定的、可重用的、交互式的API以及简单方便的功能测试。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。Swagger
让部署管理和使用功能强大的API从未如此简单。
作用:
- 根据基于规范的标准设计和建模API
- 几乎可以用任何语言为您的API构建稳定,可重用的代码
- 使用交互式API文档改善开发人员体验
- 对您的API执行简单的功能测试,而无需开销
- 在您的API架构中设置和实施API样式指南
一 、swagger的创建
- 新建
asp.net core
项目 nuget
上安装Swashbuckle.AspNetCore
Swashbuckle
有三个主要组件:Swashbuckle.AspNetCore.Swagger
:一个Swagger
对象模型和中间件,用于将SwaggerDocument
对象公开为JSON
端点。Swashbuckle.AspNetCore.SwaggerGen
:一个Swagger
生成器,可SwaggerDocument
直接从路由,控制器和模型构建对象。它通常与Swagger
端点中间件结合使用,以自动显示Swagger JSON
。Swashbuckle.AspNetCore.SwaggerUI
:Swagger UI
工具的嵌入式版本。它解释了Swagger JSON
,以便为描述Web API
功能构建丰富,可定制的体验。它包括用于公共方法的内置测试工具。
- 在
Startup
的ConfigureServices
配置服务中添加中间件
public void ConfigureServices(IServiceCollection services)
{
services.Configure<CookiePolicyOptions>(options =>
{
// This lambda determines whether user consent for non-essential cookies is needed for a given request.
options.CheckConsentNeeded = context => true;
options.MinimumSameSitePolicy = SameSiteMode.None;
});
services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" });
});
}
- 在
Startup
的Configure
配置服务中启用中间件
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
else
{
app.UseExceptionHandler("/Home/Error");
// The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
app.UseHsts();
}
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseCookiePolicy();
app.UseMvc(routes =>
{
routes.MapRoute(
name: "default",
template: "{controller=Home}/{action=Index}/{id?}");
});
app.UseSwagger();
app.UseSwaggerUI(c =>
{
c.InjectJavascript("");
c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
});
}
- 启动程序,然后键入url
swagger/index.html
或者swagger
- 修改Web API项目首页重定向
在 Properties >> launchSettings.json
文件中更改默认配置 >> 启用 "launchUrl": "swagger"
配置
{
"iisSettings": {
"windowsAuthentication": false,
"anonymousAuthentication": true,
"iisExpress": {
"applicationUrl": "http://localhost:49833",
"sslPort": 44387
}
},
"profiles": {
"IIS Express": {
"commandName": "IISExpress",
"launchBrowser": true,
"launchUrl": "swagger",
"environmentVariables": {
"ASPNETCORE_ENVIRONMENT": "Development"
}
},
"SwaggerTest": {
"commandName": "Project",
"launchBrowser": true,
"launchUrl": "http://localhost:49833/swagger",
"applicationUrl": "https://localhost:5001;http://localhost:5000",
"environmentVariables": {
"ASPNETCORE_ENVIRONMENT": "Development"
}
}
}
}
7.为控制器中每个方法添加注释,启用XML注释为未记录的公共类型和成员提供调试信息 项目 >> 属性 >> 生成
修改Startup
的 ConfigureServices
配置服务
public void ConfigureServices(IServiceCollection services)
{
services.Configure<CookiePolicyOptions>(options =>
{
// This lambda determines whether user consent for non-essential cookies is needed for a given request.
options.CheckConsentNeeded = context => true;
options.MinimumSameSitePolicy = SameSiteMode.None;
});
services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" });
//添加xml文件
var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
c.IncludeXmlComments(xmlPath);
});
}
- 添加控制器,启动 创建成功
二 、注意事项
1.启动后出现 No operations defined in spec! 问题
在查看/swagger/v1/swagger.json
文件后发现是没有配置parh
打开后内容是:
{"swagger":"2.0","info":{"version":"v1","title":"My API"},"paths":{},"definitions":{}}
解决:该项目中未添加API控制器,注意必须是API控制器,并且需要在处理方法上添加HTTP标记
/// <summary>
/// Delete
/// </summary>
/// <param name="ids">删除id列表</param>
/// <returns>被成功删除id列表</returns>
[HttpDelete]
public ActionResult<IEnumerable<string>> Delete(params string[] ids)
{
if (ids == null)
return NoContent();
return ids;
}
/// <summary>
/// Update
/// </summary>
/// <param name="id">Update id</param>
/// <returns></returns>
[HttpPut]
public IActionResult Update(string id)
{
return Content("Update id:" + id);
}
/// <summary>
/// Add
/// </summary>
/// <param name="param">Add ids</param>
/// <returns></returns>
[HttpPost]
public IActionResult Add(params string[] param)
{
return Content(string.Join(",", param));
}
2.启动后出现 Failed to load API definition.
错误
using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
namespace SwaggerTest.Controllers
{
[Route("api/[controller]")]
[ApiController]
public class DefaultController : ControllerBase
{
/// <summary>
/// Delete
/// </summary>
/// <param name="ids">删除id列表</param>
/// <returns>被成功删除id列表</returns>
//[HttpDelete]
public ActionResult<IEnumerable<string>> Delete(params string[] ids)
{
if (ids == null)
return NoContent();
return ids;
}
/// <summary>
/// Update
/// </summary>
/// <param name="id">Update id</param>
/// <returns></returns>
[HttpPut]
public IActionResult Update(string id)
{
return Content("Update id:" + id);
}
/// <summary>
/// Add
/// </summary>
/// <param name="param">Add ids</param>
/// <returns></returns>
[HttpPost]
public IActionResult Add(params string[] param)
{
return Content(string.Join(",", param));
}
}
}
原因:控制器中出现未被HTTP标记的方法
解决方案:删除该方法或者添加相应的HTTP标记
官网文档:https://docs.microsoft.com/en-us/aspnet/core/tutorials/getting-started-with-swashbuckle?view=aspnetcore-2.2&tabs=netcore-cli#add-and-configure-swagger-middleware
更多请参考swagger官网:https://swagger.io/
更多推荐
所有评论(0)