我们先简单介绍下什么是Swagger,主要是用来干嘛??
在Swagger诞生之前,我们通常在开发接口的过程中,需要前后端共同维护一个接口文档,然后大家按照接口文档的规范进行对接。接口文档俨然成了接口开发过程中不可或缺的一部分,然而对于大部分喜欢敲代码的同志们来说,写文档简直头疼,并且一般项目后期往往会由于疏忽未能及时更新文档,导致代码和接口文档不一致,这中间就有点道不清说不明了。
正是在这种大环境下,Swagger及时出现,解放了前后端开发人员对接口文档的维护压力。Swagger实际上就是一个自动生成规范接口文档的工具,由服务端设计人员调用,我们只需要按照它的格式要求在代码中添加注释即可。
好了,下面我们开始步入正题,如何快速搭建Swagger项目。
首先,我们需要添加.NetCore Web API应用程序。
![](https://img.laitimes.com/img/9ZDMuAjOiMmIsIjOiQnIsISM9AnYldnJwAzN9c3Pn5GcuQ0MlQ0MlcnW1JkbMl3aq1EMjRkT6FFROhHMp5UMNR1TwsGVNNTRE1UeRRUT3lERNlHMD1EMjpXTzsGVNZXUE10dJRUT5hzQNBzY610MrRVT2NmMiNnSywEd5ITW110MaZHetlVdO1GT3lERNl3YXJGc5kHT20ESjBjUIF2Lc12bj5SYphXa5VWen5WY35iclN3Ztl2Lc9CX6MHc0RHaiojIsJye.png)
然后,在项目中添加如下Nuget程序包。
添加Swagger引用之后,在项目中注册并使用Swagger.
首先,注册服务。
1 public void ConfigureServices(IServiceCollection services)
2 {
3 services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
4 //注册Swagger服务
5 services.AddSwaggerGen(s =>
6 {
7 //基本信息配置
8 s.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo
9 {
10 Version = "v1",
11 Title = "个人测试",
12 Description = "仅供测试使用",
13 Contact = new Microsoft.OpenApi.Models.OpenApiContact { Email = "[email protected]" }
14 });
15 //包含应用程序对应的Swagger xml文档
16 var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
17 var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
18 s.IncludeXmlComments(xmlPath);
19 });
20 }
对于XML文档,我们还需要在生成时指定xml输出路径。我这里是指定的项目根目录。这里有个禁止显示警告配置:添加了1591(用于解决未添加xml说明的警告)
然后,我们添加Swagger中间件。
1 public void Configure(IApplicationBuilder app, IHostingEnvironment env)
2 {
3 if (env.IsDevelopment())
4 {
5 app.UseDeveloperExceptionPage();
6 }
7 else
8 {
9 // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
10 app.UseHsts();
11 }
12 app.UseHttpsRedirection();
13 app.UseMvc();
14 //使用Swagger
15 app.UseSwagger();
16 app.UseSwaggerUI(s =>
17 {
18 //指定json文件
19 s.SwaggerEndpoint("/swagger/v1/swagger.json", "My API");
20 //默认前缀swagger 此处去掉前缀 直接根目录访问
21 s.RoutePrefix = string.Empty;
22 });
23 }
这里有个地方大家需要注意下:s.SwaggerEndpoint("/swagger/v1/swagger.json", "My API");指定json文件url的时候,url里面的v1需要和服务注册时:s.SwaggerDoc("v1", "")这里的v1对应一致。
最后,我们只需要在启动项目,在浏览器中输入URL:https://localhost:5001/index.html 端口以项目实际启动的端口为准.
大家可以看到默认的接口方法中:
这里的“Get方式获取”就是我们在项目接口方法体上添加的xml注释说明。
项目搭建成功啦!!!文中如有描述不对的地方,欢迎各位小伙伴前来交流。