首页 / 知识
Swagger实例分享(VS+WebApi+Swashbuckle)
2023-04-11 15:23:00
Swagger实例分享(VS+WebApi+Swashbuckle)
Swagger可以很方便的为发布的WebApi自动生成优雅的文档，不需额外自己编写，只需为项目配置好，是一个很好用的工具，做一个简单的Demo和大家分享一下~
1、使用HuGet导入Swashbuckle包
2、修改SwaggerConfig.cs
导入Swashbuckle后会自动在站点的App_Start文件夹下生成SwaggerConfig.cs，用于配置Swagger页面。配置的东西很多，下面只列举我个人需要的简单的配置（因为其他没研究）。
1publicclassSwaggerConfig
2{
3publicstaticvoidRegister()
4{
5varthisAssembly=typeof(SwaggerConfig).Assembly;
6
7GlobalConfiguration.Configuration
8.EnableSwagger(c=>
9{
10c.SingleApiVersion("v1","MyWebApi").Contact(x=>
11{
12x.Name("Bobbie");//配置界面头部描述
13});
14
15c.IncludeXmlComments(GetXmlCommentsPath("/bin/WarRoom.WebApi.XML"));//配置模板XML路径
16
17})
18.EnableSwaggerUi(c=>
19{
c.InjectJavaScript(Assembly.GetExecutingAssembly(),"MyWebApi.Scripts.Swagger_CN.js");//配置汉化js文件
20});
21}
22
23privatestaticstringGetXmlCommentsPath(stringXmlPath)
24{
25return$@"{System.AppDomain.CurrentDomain.BaseDirectory}"+XmlPath;
26}
27}
3、配置项目属性
主要是设置“生成”下的几个配置，就是我画红框框的，下面解释一下几个配置的作用：
(1)禁止警告1591是属于禁止缺少注释的警告的，不然没有头部注释的类、函数都会有警告的下划线，看着不舒服（但该警告不影响使用）。
(2)勾选XML文档文件，会自动生成一个路径，这个路径要于SwaggerConfig.cs中配置的一致：
c.IncludeXmlComments(GetXmlCommentsPath("/bin/WarRoom.WebApi.XML"));
由此其实已经配置完成，下面进行测试：
4、测试
新建一个Controller，文件名为DemoController.cs：
1publicclassDemoController:ApiController
2{
3///<summary>
4///我就是PostTest方法
5///</summary>
6///<paramname="name">参数1</param>
7///<returns></returns>
8[HttpGet]
9publicstringPostTest(stringname)
10{
11stringresult="Hello"+name;
12returnresult;
13}
然后运行，访问localhost:27827/Swagger(网址端口看自己的项目)，可以看到如下界面就是成功了：
页面会将接口路径、接口函数、注释、参数等基本信息都自动生成，还提供接口测试功能(单击TryitOut)，可以测试接口(可直接输入参数)。
5、汉化
有些朋友喜欢中文，这边也测试一下汉化的功能，主要就是添加一个汉化功能的JS文件，并在SwaggerConfig.cs配置导入即可：
（1）新建名为Swagger_CN.js的文件，放在Scripts文件夹下：
1'usestrict';
2/**
3*Translatorfordocumentationpages.
4*
5*Toenabletranslationyoushouldincludeoneoflanguage-filesinyourindex.html
6*after<scriptsrc='lang/translator.js'type='text/javascript'></script>.
7*Forexample-<scriptsrc='lang/ru.js'type='text/javascript'></script>
8*
9*Ifyouwishtotranslatesomenewtexstsyoushoulddotwothings:
10*1.Addanewphrasepair("NewPhrase":"NewTranslation")intoyourlanguagefile(forexamplelang/ru.js).Itwillbegreatifyouadditinotherlanguagefilestoo.
11*2.Markthattextittemplatesthisway<anyHtmlTagdata-sw-translate>NewPhrase</anyHtmlTag>or<anyHtmlTagdata-sw-translatevalue='NewPhrase'/>.
12*Themainthinghereisattributedata-sw-translate.Onlyinnerhtml,title-attributeandvalue-attributearegoingtotranslate.
13*
14*/
15window.SwaggerTranslator={
16_words:[],
17translate:function(){
18var$this=this;
19$('[data-sw-translate]').each(function(){
20$(this).html($this._tryTranslate($(this).html()));
21$(this).val($this._tryTranslate($(this).val()));
22$(this).attr('title',$this._tryTranslate($(this).attr('title')));
23});
24},
25_tryTranslate:function(word){
26returnthis._words[$.trim(word)]!==undefined?this._words[$.trim(word)]:word;
27},
28learn:function(wordsMap){
29this._words=wordsMap;
30}
31};
32/*jshintquotmark:double*/
33window.SwaggerTranslator.learn({
34"Warning:Deprecated":"警告：已过时",
35"ImplementationNotes":"实现备注",
36"ResponseClass":"响应类",
37"Status":"状态",
38"Parameters":"参数",
39"Parameter":"参数",
40"Value":"值",
41"Description":"描述",
42"ParameterType":"参数类型",
43"DataType":"数据类型",
44"ResponseMessages":"响应消息",
45"HTTPStatusCode":"HTTP状态码",
46"Reason":"原因",
47"ResponseModel":"响应模型",
48"RequestURL":"请求URL",
49"ResponseBody":"响应体",
50"ResponseCode":"响应码",
51"ResponseHeaders":"响应头",
52"HideResponse":"隐藏响应",
53"Headers":"头",
54"Tryitout!":"试一下！",
55"Show/Hide":"显示/隐藏",
56"ListOperations":"显示操作",
57"ExpandOperations":"展开操作",
58"Raw":"原始",
59"can'tparseJSON.Rawresult":"无法解析JSON.原始结果",
60"ModelSchema":"模型架构",
61"Model":"模型",
62"apply":"应用",
63"Username":"用户名",
64"Password":"密码",
65"Termsofservice":"服务条款",
66"Createdby":"创建者",
67"Seemoreat":"查看更多：",
68"Contactthedeveloper":"联系开发者",
69"apiversion":"api版本",
70"ResponseContentType":"响应内容类型",
71"fetchingresource":"正在获取资源",
72"fetchingresourcelist":"正在获取资源列表",
73"Explore":"浏览",
74"ShowSwaggerPetstoreExampleApis":"显示SwaggerPetstore示例Apis",
75"Can'treadfromserver.Itmaynothavetheappropriateaccess-control-originsettings.":"无法从服务器读取。可能没有正确设置access-control-origin。",
76"Pleasespecifytheprotocolfor":"请指定协议：",
77"Can'treadswaggerJSONfrom":"无法读取swaggerJSON于",
78"FinishedLoadingResourceInformation.RenderingSwaggerUI":"已加载资源信息。正在渲染SwaggerUI",
79"Unabletoreadapi":"无法读取api",
80"frompath":"从路径",
81"serverreturned":"服务器返回"
82});
83$(function(){
84window.SwaggerTranslator.translate();
85});
（2）将Swagger_CN.js设置为“嵌入的资源”
属性->生成操作->设置为“嵌入的资源”
（3）配置SwaggerConfig.cs
在EnableSwaggerUi下添加：
c.InjectJavaScript(Assembly.GetExecutingAssembly(),"MyWebApi.Scripts.Swagger_CN.js");
注：MyWebApi.Scripts.Swagger_CN.js格式为：项目名.文件夹名.JS文件名
这个可以看上面的SwaggerConfig.cs文件配置。然后再次运行：
现在就可以看到你日思夜想的中文了~
|
最新内容
相关内容
python调用方法必须实例化么
python调用方法必须实例化么，代码，培训，方法，静态，工厂，参数，程序，对象，实例，定义，python类中的实例方法和静态方法，在调用时，是有区别的。静态
python代码中优化提速的小技巧分享
python代码中优化提速的小技巧分享，代码，培训，
python常见面试题及答案分享
python常见面试题及答案分享，代码，管理，培训，数据，名称，系统，情况，企业，变量，模块，在经历一段时间的学习后，就可以去面试找工作了，一提到面试，虽
python类和实例是什么
python类和实例是什么，概念，培训，地址，数据，下来，实例，参数，方法，属性，变量，面向对象最重要的概念就是类(Class)和实例(Instance)，必须牢记类
python怎么调用实例方法
python怎么调用实例方法，代码，培训，方法，对比，参数，实例，空间，变量，定义，函数，在Python的类体中定义的方法默认都是实例方法，也示范了通过对象
python如何实例化对象
python如何实例化对象，培训，名称，实例，括号，关键字，对象，函数，字母，方式，以上，python中同样使用关键字class创建一个类，类名称第一个字母大写,python类和实例是什么
python类和实例是什么，地址，培训，概念，数据，下来，实例，参数，方法，属性，变量，面向对象最重要的概念就是类(Class)和实例(Instance)，必须牢记类
python实例方法的使用注意
python实例方法的使用注意，培训，实例，方法，对象，定义，以上，参数，更多，内容，python实例方法的使用注意1、实例方法是从属于实例对象的方法，定
python实例创建销毁的函数整理
python实例创建销毁的函数整理，培训，实例，对象，方法，函数，之前，垃圾，初始化，类别，以上，python实例创建销毁的函数整理说明1、_new_在对象实例
python实例方法中self的作用
python实例方法中self的作用，培训，实例，方法，作用，参数，对象，以上，程序，教程，更多，python实例方法中self的作用说明1、无论是创建类的构造方
关于c＃：是否有一种方法可以获取基于
关于c＃：是否有一种方法可以获取基于任意xml的System.Configuration.Configuration实例？，关于c＃：是否有一种方法可以获取基于任意xml的Sy
关于c＃：创建单实例WPF应用程序的正确
关于c＃：创建单实例WPF应用程序的正确方法是什么？，关于c＃：创建单实例WPF应用程序的正确方法是什么？，控制台,窗体,只读,比我，What is the cor