关于swagger
设计是API开发的基础。Swagger使API设计变得轻而易举，为开发人员、架构师和产品所有者提供了易于使用的工具。
官方网址：https://swagger.io/solutions/api-design/
在没有接触Swagger之前，使用Web Api的时候，我们都是使用word文档提供接口说明的，比较尬，使用文档不方便的地方太多了，比如，当时使用的时候是可以马上找到的，但是时间久了，你就不记得了，找不到了，比如，调试的时候，出现问题，你就不知道到底是使用方的问题，还是提供方的问题，测试的时候不方便，当然，可以使用Postman来模拟请求，但是需要提供JSON数据的时候还是很不方便的，需要自己构造数据等等。接触到Swagger后，这些问题迎刃而解，下面一起学习一下在Asp.Net Web Api中怎么使用Swagger。
一、新建Web Api解决方案，新建ContactController
public class ContactController : ApiController, IResourceService<Contact>
{
static List<Contact> contacts;
static int counter = 2;
static ContactController()
{
contacts = new List<Contact>();
contacts.Add(new Contact
{
Id = 1,
Name = "dengwei",
PhoneNo = "8378",
EmailAddress = "[email protected]",
Address = "深圳市福田区"
});
contacts.Add(new Contact
{
Id = 2,
Name = "lisi",
PhoneNo = "8379",
EmailAddress = "[email protected]",
Address = "深圳市南山区"
});
}
/// <summary>
/// 根据Id获取contact对象
/// </summary>
/// <param name="id">id</param>
/// <returns>返回继承自IEnumerable的对象</returns>
public JsonResult<Contact> Get(int id)
{
var contact = contacts.Where(x => x.Id == id).FirstOrDefault();
return Json<Contact>(contact);
}
/// <summary>
/// 新增contact对象
/// </summary>
/// <param name="model">contact对象</param>
public JsonResult<ResultData> Post(Contact model)
{
Interlocked.Increment(ref counter);
model.Id = counter;
contacts.Add(model);
return Json<ResultData>(new ResultData { Code = 0, Message = "success" });
}
/// <summary>
/// 修改contact对象
/// </summary>
/// <param name="model">contact对象</param>
public JsonResult<ResultData> Put(Contact model)
{
contacts.Remove(contacts.First(x => x.Id == model.Id));
contacts.Add(model);
return Json<ResultData>(new ResultData { Code = 0, Message = "success" });
}
/// <summary>
/// 根据Id删除contact对象
/// </summary>
/// <param name="id">Id</param>
public JsonResult<ResultData> Delete(int id)
{
contacts.Remove(contacts.First(x => x.Id == id));
return Json<ResultData>(new ResultData { Code = 0, Message = "success" });
}
}
我们可以看到，这个控制器类继承自IResourceService的接口，这个接口中一共四个方法：Get,Post,Put,Delete，说到这里不得不提一下RESTful 架构，我个人的理解就是对资源的增删查改，所以我也只写了四个方法：
Get：查询
Post：新增
Put：修改
Delete：删除
public interface IResourceService<T> where T : class
{
JsonResult<T> Get(int id);
JsonResult<ResultData> Post(T model);
JsonResult<ResultData> Put(T model);
JsonResult<ResultData> Delete(int id);
}
相关实体类：
public class ResultData
{
/// <summary>
/// 返回码 0 表示成功 其余表示失败
/// </summary>
public int Code { get; set; }
/// <summary>
/// 状态描述
/// </summary>
public string Message { get; set; }
}
public class Contact
{
/// <summary>
/// ID
/// </summary>
public int Id { get; set; }
/// <summary>
/// 姓名
/// </summary>
public string Name { get; set; }
/// <summary>
/// 电话
/// </summary>
public string PhoneNo { get; set; }
/// <summary>
/// 邮箱
/// </summary>
public string EmailAddress { get; set; }
/// <summary>
/// 地址
/// </summary>
public string Address { get; set; }
}
Api接口写完之后，修改解决方案输出xml文档
然后通过NuGet安装Swagger
装完成之后，修改SwaggerConfig中的xml路径为你刚才修改的解决方案的xml输出路径。
c.IncludeXmlComments(string.Format("{0}/bin/ReallyWantToApi.XML",System.AppDomain.CurrentDomain.BaseDirectory));
运行，在地址后面出入swagger回车，Api在线文档出来了，就是这么简单。如果你的Api在线文档运行的时候有异常，那么，可以肯定你的Api接口定义是不符合规范的。
下面来测试一下，接口是否可用：测试Get，返回成功了，完美。
测试POST，非常的爽，旁边已经提供了相关的JSON模板，点击一下，然后修改你需要的Value，Try it Out
好啦！就记录到这里。。。。每天进步一点点，祝各位老板中秋节快乐！
原文地址：https://www.cnblogs.com/dwBurning/p/swagger.html