《Asp.Net Core3 + Vue3入坑教程》-Net Core项目搭建与Swagger配置步骤
简介
《Asp.Net Core3 + Vue3入坑教程》 此教程仅适合新手入门或者前后端分离尝试者。可以根据图文一步一步进操作编码也可以选择直接查看源码。每一篇文章都有对应的源码
教程后期会将 .Net Core 3升级成 .Net Core 5
目录
《Asp.Net Core3 + Vue3入坑教程》系列教程目录
Asp.Net Core后端项目
- 后端项目搭建与Swagger配置步骤
- (暂未发表敬请期待...)CORS跨域问题处理
- (暂未发表敬请期待...)AutoMapper & Restful API
- (暂未发表敬请期待...)EF Core & Postgresql
- (暂未发表敬请期待...).Net Core 3升级成 .Net Core 5
- (暂未发表敬请期待...)JWT
Vue3 前端项目
暂未发表敬请期待...
本文简介
本文为《Asp.Net Core3 + Vue3入坑教程》系列教程的后端开篇,主要介绍 Asp.Net Core Web后端项目的搭建流程与Swagger配置。
Simple项目搭建流程与Swagger配置步骤
新建项目
引入Swagger Nuget包
配置Starup.cs
代码如下:
using System; using System.Collections.Generic; using System.Linq; using System.Threading.Tasks; using Microsoft.AspNetCore.Builder; using Microsoft.AspNetCore.Hosting; using Microsoft.AspNetCore.Http; using Microsoft.Extensions.DependencyInjection; using Microsoft.Extensions.Hosting; using Simple_Asp.Net_Core.ServiceProvider; namespace Simple_Asp.Net_Core { public class Startup { // This method gets called by the runtime. Use this method to add services to the container. // For more information on how to configure your application, visit https://go.microsoft.com/fwlink/?LinkID=398940 public void ConfigureServices(IServiceCollection services) { services.AddMvc(); services.AddSwagger(); } // This method gets called by the runtime. Use this method to configure the HTTP request pipeline. public void Configure(IApplicationBuilder app, IWebHostEnvironment env) { if (env.IsDevelopment()) { app.UseDeveloperExceptionPage(); app.UseSwagger(); app.UseSwaggerUI(c => { c.SwaggerEndpoint("/swagger/v1/swagger.json", "ApiHelp V1"); }); } app.UseRouting(); app.UseEndpoints(endpoints => endpoints.MapDefaultControllerRoute()); } } }
配置XML 文档文件
目的是让项目的注释能够展示在swagger页面上 。XML 文档文件的路径需要与下一步Swagger扩展类的文件路径一致
var xmlPath = Path.Combine(basePath, "Simple_Asp.Net_Core.xml");
新建文件夹ServiceProvider,增加Swagger扩展类
当前Swagger扩展类,包含了很多内容,后续会陆续使用上
代码如下:
using System; using System.IO; using Microsoft.Extensions.DependencyInjection; using Microsoft.OpenApi.Models; namespace Simple_Asp.Net_Core.ServiceProvider { public static class Swagger { public static void AddSwagger(this IServiceCollection services) { services.AddSwaggerGen(option => { option.SwaggerDoc("v1", new OpenApiInfo { Version = "0.0.1", Title = "Simple API", Description = "框架说明文档", TermsOfService = null, Contact = new OpenApiContact { Name = "Simple", Email = string.Empty, Url = null } }); // 读取xml信息 var basePath = AppContext.BaseDirectory; var xmlPath = Path.Combine(basePath, "Simple_Asp.Net_Core.xml");option.IncludeXmlComments(xmlPath, true); // Add security definitions option.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme() { ad8 Description = "Please enter into field the word 'Bearer' followed by a space and the JWT value", Name = "Authorization", In = ParameterLocation.Header, Type = SecuritySchemeType.ApiKey, }); option.AddSecurityRequirement(new OpenApiSecurityRequirement { { new OpenApiSecurityScheme { Reference = new OpenApiReference() { Id = "Bearer", Type = ReferenceType.SecurityScheme } }, Array.Empty<string>() } }); }); } } }
修改launchSettings.json
目的是让项目启动页为Swagger页面
新建Controllers文件夹,新增ValuesController
代码如下:
using System; using System.Collections.Generic; using System.Linq; using System.Threading.Tasks; using Microsoft.AspNetCore.Mvc; // For more information on enabling Web API for empty projects, visit https://go.microsoft.com/fwlink/?LinkID=397860 namespace Simple_Asp.Net_Core.Controllers { [Route("api/[controller]")] [ApiController] public class ValuesController : ControllerBase { // GET: api/<ValuesController1> [HttpGet] public IEnumerable<string> Get() { return new string[] { "value1", "value2" }; } // GET api/<ValuesController1>/5 [HttpGet("{id}")] public string Get(int id) { return "value"; } // POST api/<ValuesController1> [HttpPost] public void Post([FromBody] string value) { } // PUT api/<ValuesController1>/5 [HttpPut("{id}")] public void Put(int id, [FromBody] string value) { } // DELETE api/<ValuesController1>/5 [HttpDelete("{id}")] public void Delete(int id) { } } }
运行网站
利用swagger调用接口
请求结果返回404的错误,发现路由配置错误,修改路由配置
再次运行项目,调用接口,这一次成功返回消息!
最后一步取消警告
由于引入了Swagger导致VS多了CS1591警告,也可以不取消此警告
Simple项目的搭建与Swagger配置结束!
总结
Swagger作为前后端分离开 ad8 发必备工具,不仅可以作为前后端同事交流的文档也有助于我们更直观的管理API文档。在开发过程中针对Controller的职能与用途,需要做好必要注释、良好的注释为前后端交流和后期维护都有很重要的作用。
GitHub源码
注意:源码调试过程中如果出现xml文件路径错误,需要参照Swagger配置“配置XML 文档文件”步骤,取消勾选然后再选中 ,将XML路径设置成与你的电脑路径匹配!
https://github.com/Impartsoft/Simple_Asp.Net_Core/tree/master/Simple_Asp.Net_Core 1.Swagger
参考资料
微软官方文档 https://docs.microsoft.com/zh-cn/aspnet/core/?view=aspnetcore-5.0
Swagger官网 https://swagger.io/
- Asp.Net Core 项目搭建 基础配置 和MySql 的使用
- C#实现多级子目录Zip压缩解压实例 NET4.6下的UTC时间转换 [译]ASP.NET Core Web API 中使用Oracle数据库和Dapper看这篇就够了 asp.Net Core免费开源分布式异常日志收集框架Exceptionless安装配置以及简单使用图文教程 asp.net core异步进行新增操作并且需要判断某些字段是否重复的三种解决方案 .NET Core开发日志
- ASP.NET Core项目配置教程(6)
- 跟我学: 使用 fireasy 搭建 asp.net core 项目系列之三 —— 配置
- Asp.Net Core 项目实战之权限管理系统(1) 使用AdminLTE搭建前端
- .NET Core实战项目之CMS 第二章 入门篇-快速入门ASP.NET Core看这篇就够了
- 用Swashbuckle给ASP.NET Core的项目自动生成Swagger的API帮助文档
- ZopCommerce Asp.Net Core 1.x版教程-第0篇 项目开发环境部署
- ASP.NET Core实现类库项目读取配置文件
- Asp.Net Core 2.0 项目实战(6)Redis配置、封装帮助类RedisHelper及使用实例
- Asp.Net Core + Ocelot 网关搭建:路由简单配置
- 解决ASP.NET Core VS2015 没有“新搭建基架的项目” no New Scaffolded Item
- [置顶] ASP.NET Core ZopCommerce开源项目实战教程
- ASP.NET Core新建项目教程(3)
- 用Swashbuckle给ASP.NET Core的项目自动生成Swagger的API帮助文档
- asp.net core webapi项目配置全局路由
- 跟我学: 使用 fireasy 搭建 asp.net core 项目系列之二 —— 准备
- ASP.NET Core配置教程之读取配置信息
- IT咨询顾问:一次吐血的项目救火 java或判断优化小技巧 asp.net core Session的测试使用心得 【.NET架构】BIM软件架构02:Web管控平台后台架构 NetCore入门篇:(十一)NetCore项目读取配置文件appsettings.json 使用LINQ生成Where的SQL语句 js_jquery_创建cookie有效期问题_时区问题
- dotnet Core Asp.net 项目搭建