本次小记系列计划有如下内容
2、Swashbuckle.AspNetCore(v2.5.0)使用小记
3、Ocelot与Swashbuckle.AspNetCore集成使用小记
4、Consul使用小记
5、Nginx使用小记
6、IdentityServer4(2.2.0)使用小记
7、Dotnetcore.CAP使用小记
以上内容都是以《Ocelot(v7.0.6)使用小记》为基础的示例整合
========================================
本文不涉及任何概念,如果想了解swagger是什么,请自己在园子中搜索即可。
系统:Windows 10
IDE:vs2017最新版(截止到2018年7月)
SDK:.Net Core 2.1
涉及到的Nuget项目有:Swashbuckle.AspNetCore(v2.5.0)
首先这篇使用小记的内容是在《Ocelot(v7.0.6)使用小记》的基础之上进行的,请大家根据链接自己跳入
我们已经建立了3个WebAPI的项目,其中有2个分别叫做DogService、CatService,我们先在这两个项目里面进行测试
首先在DogService的项目上点击右键,在nuget中搜索Swashbuckle.AspNetCore,几天没用,已经更新到了3.0.0版本了,很快呀
搜索到了之后,右侧点击安装即可
出现以上提示,说明安装完毕并成功,我们进行下一步操作
我们需要在DogService项目Startup文件的ConfigureServices做如下修改:
![](https://images.cnblogs.com/OutliningIndicators/ContractedBlock.gif)
public void ConfigureServices(IServiceCollection services) { services.AddMvc(); services.AddSwaggerGen(options => { options.SwaggerDoc("v1", new Info { Version = "Version 1.0", Title = "xxxxxx的API文档", Description = "xxx作者" }); }); }
我们需要在DogService项目Startup文件的Configure做如下修改:
![](https://images.cnblogs.com/OutliningIndicators/ContractedBlock.gif)
public void Configure(IApplicationBuilder app, IHostingEnvironment env) { if (env.IsDevelopment()) { app.UseDeveloperExceptionPage(); } else { app.UseHsts(); } app.UseMvc(); app.UseSwagger(); app.UseSwaggerUI(c => { c.SwaggerEndpoint("/swagger/v1/swagger.json", "OrgAPI"); c.DocExpansion(DocExpansion.None); }); }
设置我们已经修改完毕,接下来我们通过dotnet运行一下
我们看一下,已经可以正常的访问了,访问的地址为http://localhost:6001/swagger
因为Swashbuckle的默认路径为http://xxxxxx:xxx/swagger,我这些不知道大家能否看懂是什么意思
展开之后是这个样子滴,感觉配色还是完全可以接受的,还挺好看的。
接下来我们在swagger里增加xml的描述功能,比如控制器里的某个方法的注释可以在swagger里面显示出来,这样有利于前端的同学理解其意义
首先我们在DogService的控制器中的Test()方法加上注释
在DogService项目上点击右键,点击属性,点击生成,把xml文档文件前面的✔打上并保存
那个xml的文件路径是可以自己修改的,这里我直接使用默认的路径了
配置完毕之后,我们把DogService项目重新生成一下,然后通过dotnet命令运行起来
看到上图中出现了一个DogService.xml的文件,对咯,这个就是给swagger使用的说明描述文件,我们可以看一下里面是什么内容
![](https://images.cnblogs.com/OutliningIndicators/ContractedBlock.gif)
<?xml version="1.0"?> <doc> <assembly> <name>DogService</name> </assembly> <members> <member name="M:DogService.Controllers.ValuesController.Test"> <summary> 寻找一只狗 </summary> <returns></returns> </member> </members> </doc>
接下来我们需要在startup的ConfigureServices方法中增加一个配置,那个DogService.xml就是在生成之后的那个xml文件名字,这里一定要对应上,否则会提示你找不到这个xml文件
接下来,我们通过地址来访问一下,看看效果。
我们通过上图看到,test方法的注释已经可以在swagger里正常显示了
然后CatService的swagger配置就不在描述了,跟DogService是一模一样的
在下一个文章里会介绍一下如果在Ocelot中集成swagger的方式,谢谢大家!