Swagger也称为Open API,Swagger从API文档中手动完成工做,并提供一系列用于生成,可视化和维护API文档的解决方案。简单的说就是一款让你更好的书写API文档的框架。html
咱们为何选择swagger,如今的网站开发结果愈来愈注重先后端的分离,好比之前的webFrom到如今的mvc模式都是为了这个先后端的分离。就算再如何的分离实现,也是不可避免的要进行数据交互的,那么接口的重要性就提现出来了。他成了前端和后端交互的重要途径,API文档也所以成了前端开发人员与后端开发人员的重要纽带。全部咱们有一个API文档框架岂不是美哉。前端
Swashbuckle有三个主要组件:web
Swashbuckle.AspNetCore.Swagger:Swagger对象模型和中间件,将SwaggerDocument对象公开为JSON端点。
Swashbuckle.AspNetCore.SwaggerGen:一种Swagger生成器,可SwaggerDocument直接从路由,控制器和模型构建对象。它一般与Swagger端点中间件结合使用,以自动公开Swagger JSON。
Swashbuckle.AspNetCore.SwaggerUI:Swagger UI工具的嵌入式版本。它将Swagger JSON解释为构建丰富的,可定制的Web API功能描述体验。它包括用于公共方法的内置测试线束。json
首先咱们要有一个WebAPI项目,假设咱们已经建立好了,不懂WebAPI如何建立的请看这篇文章:建立简单的WebAPI后端
好了如今咱们已经有了项目那咱们就开始添加引用吧:api
Nuget 命令行 :Install-Package Swashbuckle.AspNetCoremvc
而后配置Startup.cs 文件中的ConfigureServices方法,固然首先不要忘记引用一下using Swashbuckle.AspNetCore.Swagger命名空间,否则info类会报错。app
public void ConfigureServices(IServiceCollection services) { services.AddMvc() .SetCompatibilityVersion(CompatibilityVersion.Version_2_1) .AddJsonOptions(options => options.SerializerSettings.ContractResolver = new Newtonsoft.Json.Serialization.DefaultContractResolver());//JSON首字母小写解决; services.AddSwaggerGen(options => { options.SwaggerDoc("v1", new Info { Version = "v1", Title = " API 文档" }); }); }
而后在Configure方法中添加:框架
//容许中间件为JSON端点服务生成的Siggg app.UseSwagger(); //使中间件可以服务于轻量级用户界面(HTML、JS、CSS等),并指定SWAGJER JSON端点 app.UseSwaggerUI(c => { c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1"); // 要在应用程序的根处提供Swagger UI ,请将该RoutePrefix属性设置为空字符串 c.RoutePrefix = string.Empty; });
这样就能够启动了,配置好以上就是一个最简单的api文档示例了。首先你能够访问:http://localhost:<port>/swagger/v1/swagger.json 这个网址看到端点生成的文档。ide
固然你想看到的是这个:http://localhost:<port>/swagger ,你输入这个网址也能够,固然我把他配置成了根节点,这样直接启动根节点就是该页面。主要是上面代码中的: c.RoutePrefix = string.Empty这句代码。
咱们能够扩展一些附加信息,好比做者,许可证,服务条款等。传递给该AddSwaggerGen
方法的配置:
//Swagger生成器添加到方法中的服务集合中 services.AddSwaggerGen(options => { options.SwaggerDoc("v1", new Info { Version = "v1", Title = " API 文档", Description = "这是一个示例webapi文档", //服务条款 TermsOfService = "None", //做者信息 Contact = new Contact { Name = "ybf", Email = string.Empty, Url = "http://www.cnblogs.com/yanbigfeg/" }, //许可证 License = new License { Name = "许可证名字", Url = "http://www.cnblogs.com/yanbigfeg/" } }); });
显示结果
启用XML注释可为未记录的公共类型和成员提供调试信息。未记录的类型和成员由警告消息指示。配置Swagger以使用生成的XML文件。
在咱们实现前先设置一下项目属性:
这样就能够在项目bin下生成xml文件了。下面进行代码配置启用,仍是在Startup类中的ConfigureServices方法中,在咱们刚才配置的下面在增长如下代码:
// 设置SWAGER JSON和UI的注释路径。 var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml"; var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile); options.IncludeXmlComments(xmlPath);
使用反射主要是为了生成一个与项目文件名相同的xml文件。第二部而后是配置文件路径。这些配置好了之后。咱们就能够把方法或者类的三道斜杠(“///”)的注释添加到动做。咱们来看一下效果。
代码
界面:
注意哦,就是开启这个功能,项目会自动检测那些方法或者类没有注释,会给出警告。
固然咱们也能够取消掉:咱们在我的.csproj文件中使用分号分隔来取消警告信息:
<PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'"> <DocumentationFile>bin\Debug\netcoreapp2.1\SwaggerTest.xml</DocumentationFile> <GenerateSerializationAssemblies>On</GenerateSerializationAssemblies> <NoWarn>1701;1702;1705;1591</NoWarn> </PropertyGroup>
这样就不会有警告提示了。
接口使用者最关心的就是接口的返回内容和相应类型啦。下面展现一下201和400一个简单例子:
咱们须要在咱们的方法上添加:[ProducesResponseType(201)][ProducesResponseType(400)]
而后添加相应的状态说明:<response code="201">返回value字符串</response><response code="400">若是id为空</response>
最终代码应该是这个样子:
/// <summary> /// values带id参数的get /// </summary> /// <param name="id">id参数</param> /// <returns>返回字符串类型</returns> /// <response code="201">返回value字符串</response> /// <response code="400">若是id为空</response> // GET api/values/5 [HttpGet("{id}")] [ProducesResponseType(201)] [ProducesResponseType(400)] public ActionResult<string> Get(int id) { return "value"; }
运行起来咱们看一下结果:
本例源码下载:SwaggerTest.rar
WebApi系列文章介绍如何使用WebAPI: