zoukankan      html  css  js  c++  java
  • Asp.Net Web Api中使用Swagger

    关于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 = "dengwei@outlook.com",
                    Address = "深圳市福田区"
                });
                contacts.Add(new Contact
                {
                    Id = 2,
                    Name = "lisi",
                    PhoneNo = "8379",
                    EmailAddress = "lisi@qq.com",
                    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

  • 相关阅读:
    date题解
    pencil题解
    20155326 2017-2018-1 《信息安全系统设计基础》第5周学习总结
    2017-2018-1 20155326 20155320 实验一 开发环境的熟悉
    2017-2018-1 20155326 《信息安全系统设计基础》第四周学习总结及myod改进版的补交
    2017-2018-1 20155326 《信息安全系统设计基础》第三周学习总结
    20155326 2017-2018-1 《信息安全系统设计基础》第2周学习及课堂总结myod
    20155326 2017-2018-1 《信息安全系统设计基础》第1周学习总结
    20155326 《Java程序设计》实验五网络编程与安全实验报告
    20155326 2016-2017-2《Java程序设计》课程总结
  • 原文地址:https://www.cnblogs.com/dwBurning/p/swagger.html
Copyright © 2011-2022 走看看