Asp.Net MVC Web API 中Swagger教程，使用Swagger建立Web API幫助文件

   什麼是Swagger？

     Swagger 是一個規範和完整的框架，用於生成、描述、調用和可視化 RESTful 風格的 Web 服務。整體目標是使客戶端和文件系統做爲服務器以一樣的速度來更新。文件的方法，參數和模型緊密集成到服務器端的代碼，容許API來始終保持同步。使用Swagger可以讓咱們在線調試接口以及功能測試。如今我把Swagger集成到Asp.Net MVC 中。

   具體步驟：

  一、用Visual Studio 2017 建立一個Asp.Net Web API 項目

  從模板中選擇 Web API，這樣 VS將把 MVC、與Web API相關的文件夾和核心引用添加到咱們的應用中。（必定要選擇Web API否則後面沒有效果的，這裏主要就是在web api 裏面實現的）

建立項目後項目文檔跟文件夾結構以下

 

  二、用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(20,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>

 

 三、在控制器裏面新建一個空的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 =0;i<11;i++)
            {
                var depId = 1;
                if(i<5){depId = 1;}
                else{depId = 2;}
                var user = new Users() {
                    Id = i + 1,
                    LoginID="Wyy00"+i,
                    Pwd="mima00"+i,
                    Name="魏楊楊"+i,
                    Age=18,
                    Sex="男",
                    DepId=depId
                };
                db.Users.Add(user);
                db.SaveChanges();
            }
        }
        /// <summary>
        /// 添加部門
        /// </summary>
        public void AddDep()
        {
            for (int i = 0; i < 2; i++)
            {
                var dep = new Dep() {
                    Id=i+1,
                    Name="部門"+i,
                    Instroduce="部門介紹00"+i,
                    DepCode="BM00"+i
                };
                db.Dep.Add(dep);
                db.SaveChanges();
            }
        }

 

 

 數據庫裏面是有值的

 數據添加了記得把那兩個方法刪除了否則會添加劇複數據

 四、驗證一下Web API 是否可用，我是在谷歌瀏覽器裏面

五、引入Swagger：將Swashbuckle添加到 Web API中

安裝成功後APP_Start文件夾下面會多出來一個「SwaggerConfig.cs」配置文檔，全部Swagger相關配置都會在此進行設置。

如今簡單的配置就能夠了，也能夠用了 看效果圖：在地址看後面加 /Swagger

如今有兩個API一個是系統本身建立的Values一個是咱們本身建立的Users

裏面也能夠調用了 點開Users查詢用戶

下面的響應

六、如今都是英文的，如今來漢化一下而且顯示註釋，配置一下

首先把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);
        }
    }
}

 看效果