什么是Swagger?
Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。使用Swagger能够让我们在线调试接口以及功能测试。现在我把Swagger集成到Asp.Net MVC 中。
具体步骤:
1、用Visual Studio 2017 创建一个Asp.Net Web API 项目
从模板中选择 Web API,这样 VS将把 MVC、与Web API相关的文件夹和核心引用添加到我们的应用中。(一定要选择Web API不然后面没有效果的,这里主要就是在web api 里面实现的)
创建项目后项目文档跟文件夹结构如下
2、用Code First在Model里面创建2张表用来测试,一张用户表Users,一张部门表Dep
创建表之前先引用EF
下面是部门表跟用户表的代码,里面的关系也配置好了
using System;
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;
using System.Linq;
using System.Web; namespace SwaggerDemo.Models
{
/// <summary>
/// 用户表
/// </summary>
[Table("Users")]
public class Users
{
/// <summary>
/// Id
/// </summary>
[Key]
public int Id { get; set; }
/// <summary>
/// 登录账号
/// </summary>
[StringLength(,ErrorMessage ="登录ID不能超过20个字符")]
[Column("LoginID",TypeName ="nvarchar")]
[Display(Name ="登录账号")]
public string LoginID { get; set; }
/// <summary>
/// 密码
/// </summary>
public string Pwd { get; set; }
/// <summary>
/// 姓名
/// </summary>
public string Name { get; set; }
/// <summary>
/// 年龄
/// </summary>
public int Age { get; set; }
/// <summary>
/// 性别
/// </summary>
public string Sex { get; set; }
/// <summary>
/// 部门Id
/// </summary>
[ForeignKey("Dep")]
public int DepId { get; set; }
/// <summary>
/// 部门
/// </summary>
public virtual Dep Dep { get; set; } }
}
using System;
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;
using System.Linq;
using System.Web; namespace SwaggerDemo.Models
{
/// <summary>
/// 部门表
/// </summary>
[Table("Dep")]
public class Dep
{
/// <summary>
/// ID
/// </summary>
[Key]
public int Id { get; set; }
/// <summary>
/// 名称
/// </summary>
public string Name { get; set; }
/// <summary>
/// 部门编码
/// </summary>
public string DepCode { get; set; }
/// <summary>
/// 介绍
/// </summary>
public string Instroduce { get; set; }
/// <summary>
/// 用户
/// </summary>
public virtual IList<Users> Users { get; set; }
}
}
接下来配置数据库上下文新建一个DbConn继承DbContext
using System;
using System.Collections.Generic;
using System.Data.Entity;
using System.Linq;
using System.Web; namespace SwaggerDemo.Models
{
/// <summary>
/// 数据库上下文
/// </summary>
public class DBConn:DbContext
{
public DBConn() : base("SqlConn")
{
//默认的初始化器。这种初始化器在第一次运行程序时会创建数据库,再次运行不会再创建新的数据库。但是如果我们改变了领域类,运行程序时会抛出一个异常
Database.SetInitializer(new CreateDatabaseIfNotExists<DBConn>());
}
/// <summary>
/// 用户
/// </summary>
public DbSet<Users> Users { get; set; }
/// <summary>
/// 部门
/// </summary>
public DbSet<Dep> Dep { get; set; }
}
}
配置web.config文件,在configuration节点下面添加
<!--数据库连接-->
<connectionStrings>
<add name="SqlConn" connectionString="Data Source=数据库地址;Initial Catalog=数据库名;User ID=sa; Password=密码;MultipleActiveResultSets=True" providerName="System.Data.SqlClient" />
</connectionStrings>
3、在控制器里面新建一个空的Web API 命名Users
在里面填写一个方法查询用户的用来测试
using SwaggerDemo.Models;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Net;
using System.Net.Http;
using System.Web.Http; namespace SwaggerDemo.Controllers
{
/// <summary>
/// 用户操作
/// </summary>
public class UsersController : ApiController
{
private readonly DBConn db = new DBConn();
/// <summary>
/// 获取用户列表
/// </summary>
/// <returns></returns>
public List<UserDto> GetUsersList()
{
var udl = db.Users.ToList();
List<UserDto> list = new List<UserDto>();
foreach (var u in udl)
{
var udt= new UserDto()
{
Id = u.Id,
Name = u.Name,
Age = u.Age,
Pwd = u.Pwd,
Sex = u.Sex
};
}
return list ;
}
/// <summary>
/// 获取用户信息
/// </summary>
/// <param name="id"></param>
/// <returns></returns>
public UserDto GetUsers(int id)
{
var user = db.Users.Find(id);
var ud = new UserDto() {
Id=user.Id,
Name= user.Name,
Age= user.Age,
Pwd= user.Pwd,
Sex= user.Sex,
};
return ud;
}
}
}
要用一个Dto去接收不然会出错
using System;
using System.Collections.Generic;
using System.Linq;
using System.Web; namespace SwaggerDemo.Models
{
public class UserDto
{
public int Id { get; set; }
/// <summary>
/// 登录账号
/// </summary>
public string LoginID { get; set; }
/// <summary>
/// 密码
/// </summary>
public string Pwd { get; set; }
/// <summary>
/// 姓名
/// </summary>
public string Name { get; set; }
/// <summary>
/// 年龄
/// </summary>
public int Age { get; set; }
/// <summary>
/// 性别
/// </summary>
public string Sex { get; set; }
}
}
现在数据库还没有表的哦,所以先运行一遍把表建立,然后又添加一点数据进去方便测试。看路由里面启动项是Home控制器里面的Index,添加
using SwaggerDemo.Models;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Web.Mvc; namespace SwaggerDemo.Controllers
{
public class HomeController : Controller
{
private readonly DBConn db = new DBConn();
public ActionResult Index()
{
var u = db.Users.ToList();
var d = db.Dep.ToList(); return View();
}
}
}
运行没有出错 数据库里面也有了表
那就添加数据
private readonly DBConn db = new DBConn();
public ActionResult Index()
{
AddDep();
AddUsers();
var u = db.Users.ToList();
var d = db.Dep.ToList(); return View();
}
/// <summary>
/// 添加用户
/// </summary>
public void AddUsers()
{
for(int i =;i<;i++)
{
var depId = ;
if(i<){depId = ;}
else{depId = ;}
var user = new Users() {
Id = i + ,
LoginID="Wyy00"+i,
Pwd="mima00"+i,
Name="魏杨杨"+i,
Age=,
Sex="男",
DepId=depId
};
db.Users.Add(user);
db.SaveChanges();
}
}
/// <summary>
/// 添加部门
/// </summary>
public void AddDep()
{
for (int i = ; i < ; i++)
{
var dep = new Dep() {
Id=i+,
Name="部门"+i,
Instroduce="部门介绍00"+i,
DepCode="BM00"+i
};
db.Dep.Add(dep);
db.SaveChanges();
}
}
数据库里面是有值的
数据添加了记得把那两个方法删除了不然会添加重复数据
4、验证一下Web API 是否可用,我是在谷歌浏览器里面
5、引入Swagger:将Swashbuckle添加到 Web API中
安装成功后APP_Start文件夹下面会多出来一个“SwaggerConfig.cs”配置文档,所有Swagger相关配置都会在此进行设置。
现在简单的配置就可以了,也可以用了 看效果图:在地址看后面加 /Swagger
现在有两个API一个是系统自己创建的Values一个是我们自己创建的Users
里面也可以调用了 点开Users查询用户
下面的响应
6、现在都是英文的,现在来汉化一下并且显示注释,配置一下
首先把SwaggerConfig.cs不要的东西全部删了。强迫症没办法,干干净净看着多好哈哈,再添加一下中文语言js包
别忘了把这个js文件属性生成操作改为嵌入式资源(不然引用不到这个js)这个js网上有没有来我给你
c.InjectJavaScript(thisAssembly, "SwaggerDemo.Scripts.swaggerui.swagger_lang.js");//中文包
读取注释的话配置路径,并且项目生成要有个xml文件:右键点击项目---->属性--->生成 生成xml选项√上
读取xml :SwaggerDemo这个是项目名别搞乱了
using System.Web.Http;
using WebActivatorEx;
using SwaggerDemo;
using Swashbuckle.Application;
using System; [assembly: PreApplicationStartMethod(typeof(SwaggerConfig), "Register")] namespace SwaggerDemo
{
public class SwaggerConfig
{
public static void Register()
{
var thisAssembly = typeof(SwaggerConfig).Assembly; GlobalConfiguration.Configuration
.EnableSwagger(c =>
{
c.SingleApiVersion("v1", "SwaggerDemo");
c.IncludeXmlComments(GetXmlCommentsPath());
})
.EnableSwaggerUi(c =>
{
c.InjectJavaScript(thisAssembly, "SwaggerDemo.Scripts.swaggerui.swagger_lang.js");//中文包
});
}
private static string GetXmlCommentsPath()
{
return String.Format(@"{0}\bin\SwaggerDemo.XML", System.AppDomain.CurrentDomain.BaseDirectory);
}
}
}
看效果