使用ABP实现SwaggerUI,生成动态webapi

╰+攻爆jí腚メ 2022-07-15 09:46 385阅读 0赞

上一篇，我们是正式将ABP生成的代码项目，跑起来了，然后演示了下多租户的不同。那么这篇我们就来实现下SwaggerUI。

Q:SwaggerUI是干什么的呢？

A:他是一个能将我们的webapi，通过Swagger Api来生成一个交互式的文档。通过他可以对你的接口进行调式。

## 1、引入Swashbuckle.core ##

选择PhoneBook.WebApi，然后添加nuget包（当然你也可以通过命令行添加）。

输入“Swashbuckle.core”

[![image][]][image 1]

引入到我们的项目中。

打开 项目中的“PhoneBookWebApiModule.cs”文件.

创建一个方法“ConfigureSwaggerUi();”

![复制代码][copycode.gif]

/// <summary>
            /// 配置SwaggerUi
            /// </summary>
            private void ConfigureSwaggerUi()
            {
                Configuration.Modules.AbpWebApi().HttpConfiguration
                    .EnableSwagger(c =>
                    {
                        c.SingleApiVersion("v1", "YoYoCMS.PhoneBookAPI文档");
                        c.ResolveConflictingActions(apiDescriptions => apiDescriptions.First());
                    })
                    .EnableSwaggerUi();
            }

![复制代码][copycode.gif]

然后在Initialize()中对他进行调用。

[![image][image 2]][image_image 2]

## 2、运行项目 ##

运行项目，打开”/swagger/ui/index”路径

得到的效果

[![image][image 3]][image_image 3]

到此呢，ABP实现SwaggerUI的功能已经算是可以了。但是我们不能就这么满足了。还不够，为什么呢。因为我们还要讲我们的注释显示出来。

这样其他开发人员看到了接口名称才能说叫做API文档嘛。

## 3、对API文档进行增强 ##

大家要特别注意：

这里生成的XML文档，一定要注意是application类库中的，不是webapi类型的

是application类库、application类库、application类库

重要的事情重复三次。（ 觉得好的右边求打赏 ![Image 1][] ）[![W03\[IU\_F\_41WH6U9QZ7\]J\`H][W03_IU_F_41WH6U9QZ7_J_H]][W03_IU_F_41WH6U9QZ7_J_H_W03_IU_F_41WH6U9QZ7_J_H]

首先我们回到 方法：ConfigureSwaggerUi中，对他进行改造。

首先打开application类库的属性设置，然后在生成中找到XML文档文件，启用生成

[![image][image 4]][image_image 4]

然后再对ConfigureSwaggerUi方法进行改造

![复制代码][copycode.gif]

//将application层中的注释添加到SwaggerUI中
                        var baseDirectory = AppDomain.CurrentDomain.BaseDirectory;
                  
                        var commentsFileName = "Bin//YoYoCMS.PhoneBook.Application.xml";
                        var commentsFile = Path.Combine(baseDirectory, commentsFileName);
                        //将注释的XML文档添加到SwaggerUI中
                        c.IncludeXmlComments(commentsFile);

![复制代码][copycode.gif]

添加以下到方法中。

[![image][image 5]][image_image 5]

然后运行项目：

[![image][image 6]][image_image 6]

咦。。。怎么没有。。注释呢。。。。

[![CRC36P@9S3V\{\}Y\]7TEQ\]\]70][CRC36P_9S3V_Y_7TEQ_70]][CRC36P_9S3V_Y_7TEQ_70_CRC36P_9S3V_Y_7TEQ_70]

当然这一切的一切只是我们可以加注释，来现在我们把注释加上。。[![E\{OBPTRZT4\[8IQFV8$@LQ3X][E_OBPTRZT4_8IQFV8_LQ3X]][E_OBPTRZT4_8IQFV8_LQ3X_E_OBPTRZT4_8IQFV8_LQ3X]

[![image][image 7]][image_image 7]

[![image][image 8]][image_image 8]

然后再来运行一次项目。。。

[![image][image 9]][image_image 9]

上图我们就可以看到了。已经得到了注释信息，以后开发再也不怕哪个接口是哪个了。

## 4、修改访问方式 ##

到目前为止我们访问SwaggerUI的方式都是”/swagger/ui/index/” 这样的路径访问方式。

个人感觉不是很方面我们对它进行稍微的优化下。

我们可以看到EnableSwaggerUi，F12转到定义下。

[![image][image 10]][image_image 10]

[![image][image 11]][image_image 11]

支持路由重定向，那么我们就开始改造吧。

[![image][image 12]][image_image 12]

其实就这么一句话，改造后的访问路径“/apis/index”就可以了。

[![J5\_ULNEP~\{PT(\{XDIR\{O~BS][J5_ULNEP_PT_XDIR_O_BS]][J5_ULNEP_PT_XDIR_O_BS_J5_ULNEP_PT_XDIR_O_BS]

看看效果。

[![image][image 13]][image_image 13]

这样操作接口就比较方便了。

## 5、进行将提示语言修改为中文 ##

.EnableSwaggerUi("apis/{*assetPath}", b =>
                    {
                        b.InjectJavaScript();
                        b.InjectStylesheet();
                    });

一个 是注入JavaScript文件，一个是输入css文件。所以如果这里可以对我们的SwaggerUI界面进行自定义修改的。

需要将js文件路径注入到SwaggerUI中。

.EnableSwaggerUi("apis/{*assetPath}", b =>
                    {
                        //对js进行了拓展
                        b.InjectJavaScript(Assembly.GetExecutingAssembly(), "YoYoCMS.PhoneBook.SwaggerUi.scripts.swagger.js");
                     });

//YoYoCMS.PhoneBook.SwaggerUi.scripts.swagger.js是你的命名空间加上文件的路径.

### 很多人在这一步翻船 ###

YoYoCMS.PhoneBook 是你的项目默认命名空间

[![image][image 14]][image_image 14]

然后接下来才是你的各种文件夹结构。。

[![image][image 15]][image_image 15]

swagger.js需要设置为嵌入的资源。

[![image][image 16]][image_image 16]

请注意你的项目结构。每一个.代表的是一个文件夹

swagger.js 也放出来。

![复制代码][copycode.gif]

'use strict';
    
    /**
     * Translator for documentation pages.
     *
     * To enable translation you should include one of language-files in your index.html
     * after <script src='lang/translator.js' type='text/javascript'></script>.
     * For example - <script src='lang/ru.js' type='text/javascript'></script>
     *
     * If you wish to translate some new texsts you should do two things:
     * 1. Add a new phrase pair ("New Phrase": "New Translation") into your language file (for example lang/ru.js). It will be great if you add it in other language files too.
     * 2. Mark that text it templates this way <anyHtmlTag data-sw-translate>New Phrase</anyHtmlTag> or <anyHtmlTag data-sw-translate value='New Phrase'/>.
     * The main thing here is attribute data-sw-translate. Only inner html, title-attribute and value-attribute are going to translate.
     *
     */
    window.SwaggerTranslator = {
        _words: [],
    
        translate: function () {
            var $this = this;
            $('[data-sw-translate]').each(function () {
                $(this).html($this._tryTranslate($(this).html()));
                $(this).val($this._tryTranslate($(this).val()));
                $(this).attr('title', $this._tryTranslate($(this).attr('title')));
            });
        },
    
        _tryTranslate: function (word) {
            return this._words[$.trim(word)] !== undefined ? this._words[$.trim(word)] : word;
        },
    
        learn: function (wordsMap) {
            this._words = wordsMap;
        }
    };
    
    
    /* jshint quotmark: double */
    window.SwaggerTranslator.learn({
        "Warning: Deprecated": "警告：已过时",
        "Implementation Notes": "实现备注",
        "Response Class": "响应类",
        "Status": "状态",
        "Parameters": "参数",
        "Parameter": "参数",
        "Value": "值",
        "Description": "描述",
        "Parameter Type": "参数类型",
        "Data Type": "数据类型",
        "Response Messages": "响应消息",
        "HTTP Status Code": "HTTP状态码",
        "Reason": "原因",
        "Response Model": "响应模型",
        "Request URL": "请求URL",
        "Response Body": "响应体",
        "Response Code": "响应码",
        "Response Headers": "响应头",
        "Hide Response": "隐藏响应",
        "Headers": "头",
        "Try it out!": "试一下！",
        "Show/Hide": "显示/隐藏",
        "List Operations": "显示操作",
        "Expand Operations": "展开操作",
        "Raw": "原始",
        "can't parse JSON.  Raw result": "无法解析JSON. 原始结果",
        "Model Schema": "模型架构",
        "Model": "模型",
        "apply": "应用",
        "Username": "用户名",
        "Password": "密码",
        "Terms of service": "服务条款",
        "Created by": "创建者",
        "See more at": "查看更多：",
        "Contact the developer": "联系开发者",
        "api version": "api版本",
        "Response Content Type": "响应Content Type",
        "fetching resource": "正在获取资源",
        "fetching resource list": "正在获取资源列表",
        "Explore": "浏览",
        "Show Swagger Petstore Example Apis": "显示 Swagger Petstore 示例 Apis",
        "Can't read from server.  It may not have the appropriate access-control-origin settings.": "无法从服务器读取。可能没有正确设置access-control-origin。",
        "Please specify the protocol for": "请指定协议：",
        "Can't read swagger JSON from": "无法读取swagger JSON于",
        "Finished Loading Resource Information. Rendering Swagger UI": "已加载资源信息。正在渲染Swagger UI",
        "Unable to read api": "无法读取api",
        "from path": "从路径",
        "server returned": "服务器返回"
    });
    
    
    $(function () {
        window.SwaggerTranslator.translate();
    });

![复制代码][copycode.gif]

## 6、最终运行的效果 ##

[![image][image 17]][image_image 17]

## SwaggerUI在生产环境的隐忧 ##

有小伙伴在群里问SwaggerUI这么强大，到了生产环境是不是要手动屏蔽？

刚刚经过我的实际测试发现无须担忧这个问题。

当我们把项目发布到IIS后。

[![image][image 18]][image_image 18]

再次打开SwaggerUI

[![image][image 19]][image_image 19]

就会发现报500错误，所以这个隐忧看看不用考虑了

转载地址：http://www.cnblogs.com/wer-ltm/p/5776024.html

[image]: /images/20220715/1e5ed1697a704a21b29d7906fe47eb3f.png
[image 1]: http://images2015.cnblogs.com/blog/675038/201608/675038-20160816124901687-1494829054.png
[copycode.gif]: /images/20220715/2b09dac0191a411faa7e91175e9a890b.png
[image 2]: http://images2015.cnblogs.com/blog/675038/201608/675038-20160816124906031-901875696.png
[image_image 2]: /images/20220715/7069d72cf6274adcac6b9d97698a4915.png
[image 3]: http://images2015.cnblogs.com/blog/675038/201608/675038-20160816124909125-1357037666.png
[image_image 3]: /images/20220715/323202672bc448d7b100d6bc8a884900.png
[Image 1]: 
[W03_IU_F_41WH6U9QZ7_J_H]: http://images2015.cnblogs.com/blog/675038/201608/675038-20160819001633390-115379933.jpg
[W03_IU_F_41WH6U9QZ7_J_H_W03_IU_F_41WH6U9QZ7_J_H]: http://images2015.cnblogs.com/blog/675038/201608/675038-20160819001632875-55751949.jpg
[image 4]: http://images2015.cnblogs.com/blog/675038/201608/675038-20160816124911171-1878036101.png
[image_image 4]: /images/20220715/6093d5b69f974f73adbdfea68d0f8c5d.png
[image 5]: http://images2015.cnblogs.com/blog/675038/201608/675038-20160816124913421-1939099804.png
[image_image 5]: /images/20220715/0202cf1997b54061915f5d71efb08eae.png
[image 6]: http://images2015.cnblogs.com/blog/675038/201608/675038-20160816124916484-1461224315.png
[image_image 6]: /images/20220715/df769219596c44f79d3e6fa68175ac0e.png
[CRC36P_9S3V_Y_7TEQ_70]: http://images2015.cnblogs.com/blog/675038/201608/675038-20160816124918218-75763480.jpg
[CRC36P_9S3V_Y_7TEQ_70_CRC36P_9S3V_Y_7TEQ_70]: /images/20220715/941859887ae047c4a30fae2610543ede.png
[E_OBPTRZT4_8IQFV8_LQ3X]: http://images2015.cnblogs.com/blog/675038/201608/675038-20160816124921640-358910689.gif
[E_OBPTRZT4_8IQFV8_LQ3X_E_OBPTRZT4_8IQFV8_LQ3X]: /images/20220715/2d54b51594ee4ac496f66b2d6ec7cc16.png
[image 7]: http://images2015.cnblogs.com/blog/675038/201608/675038-20160816124923281-992094635.png
[image_image 7]: /images/20220715/90517229aac7420abbf2c05df95bcfb7.png
[image 8]: http://images2015.cnblogs.com/blog/675038/201608/675038-20160816124924984-1780475998.png
[image_image 8]: /images/20220715/5b96525ef09f4248b8d8c00c7fd0f28d.png
[image 9]: http://images2015.cnblogs.com/blog/675038/201608/675038-20160816124927750-449403723.png
[image_image 9]: /images/20220715/da881a684bc24781ad2310777e057f59.png
[image 10]: http://images2015.cnblogs.com/blog/675038/201608/675038-20160816124929796-1739340799.png
[image_image 10]: /images/20220715/7b863ea51e324438b31d0298a0dc9529.png
[image 11]: http://images2015.cnblogs.com/blog/675038/201608/675038-20160816124931687-1217103746.png
[image_image 11]: /images/20220715/e5b946996ded4a51b6e1fb999d4022eb.png
[image 12]: http://images2015.cnblogs.com/blog/675038/201608/675038-20160816124932937-1389996066.png
[image_image 12]: /images/20220715/decf6690db574cce9016fdbff917b91f.png
[J5_ULNEP_PT_XDIR_O_BS]: http://images2015.cnblogs.com/blog/675038/201608/675038-20160816124934281-927310291.gif
[J5_ULNEP_PT_XDIR_O_BS_J5_ULNEP_PT_XDIR_O_BS]: /images/20220715/f56c1cb9b6c048919d4b6b92018ddd0a.png
[image 13]: http://images2015.cnblogs.com/blog/675038/201608/675038-20160816124935921-302853594.png
[image_image 13]: /images/20220715/a729f8f71444404fb2c5bf2d1a9dfd04.png
[image 14]: http://images2015.cnblogs.com/blog/675038/201608/675038-20160816151212031-1410451781.png
[image_image 14]: /images/20220715/92764a5a7dc04ca5ae8737b462cb1350.png
[image 15]: http://images2015.cnblogs.com/blog/675038/201608/675038-20160816124940937-1356906054.png
[image_image 15]: /images/20220715/33192fb0181b45de955931c3626dce1d.png
[image 16]: http://images2015.cnblogs.com/blog/675038/201608/675038-20160816124942687-1101615488.png
[image_image 16]: /images/20220715/eba4a2d06a1945279a8e1de6c75aad4b.png
[image 17]: http://images2015.cnblogs.com/blog/675038/201608/675038-20160816124944171-2022655946.png
[image_image 17]: /images/20220715/57f859f0d07846f3aabc4b4c53764646.png
[image 18]: http://images2015.cnblogs.com/blog/675038/201608/675038-20160816170640312-2142529624.png
[image_image 18]: /images/20220715/e22f7bf4dc984635bd9c5a1e0479c797.png
[image 19]: http://images2015.cnblogs.com/blog/675038/201608/675038-20160816170647531-2069912858.png
[image_image 19]: /images/20220715/989e25af7b1246a09a0326958d1ae1d8.png