Swashbuckle.AspNetCore(v2.5.0)使用小記

本次小記系列計划有如下內容

1、Ocelot(v7.0.6)使用小記

2、Swashbuckle.AspNetCore(v2.5.0)使用小記

3、Ocelot與Swashbuckle.AspNetCore集成使用小記

4、Consul使用小記

5、Nginx使用小記

6、IdentityServer4(2.2.0)使用小記

7、Dotnetcore.CAP使用小記

以上內容都是以《Ocelot(v7.0.6)使用小記》為基礎的示例整合

========================================

本文不涉及任何概念，如果想了解swagger是什么，請自己在園子中搜索即可。

系統：Windows 10

IDE：vs2017最新版（截止到2018年7月）

SDK：.Net Core 2.1

涉及到的Nuget項目有：Swashbuckle.AspNetCore(v2.5.0)

 

首先這篇使用小記的內容是在《Ocelot(v7.0.6)使用小記》的基礎之上進行的，請大家根據鏈接自己跳入

我們已經建立了3個WebAPI的項目，其中有2個分別叫做DogService、CatService，我們先在這兩個項目里面進行測試

首先在DogService的項目上點擊右鍵，在nuget中搜索Swashbuckle.AspNetCore，幾天沒用，已經更新到了3.0.0版本了，很快呀

搜索到了之后，右側點擊安裝即可

出現以上提示，說明安裝完畢並成功，我們進行下一步操作

 

 

我們需要在DogService項目Startup文件的ConfigureServices做如下修改：

public void ConfigureServices(IServiceCollection services)
        {
            services.AddMvc();

            services.AddSwaggerGen(options =>
            {
                options.SwaggerDoc("v1", new Info
                {
                    Version = "Version 1.0",
                    Title = "xxxxxx的API文檔",
                    Description = "xxx作者"
                });
            });
        }

我們需要在DogService項目Startup文件的Configure做如下修改：

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }
            else
            {
                app.UseHsts();
            }

            app.UseMvc();
            app.UseSwagger();
            app.UseSwaggerUI(c =>
            {
                c.SwaggerEndpoint("/swagger/v1/swagger.json", "OrgAPI");
                c.DocExpansion(DocExpansion.None);
            });
        }

設置我們已經修改完畢，接下來我們通過dotnet運行一下

 

我們看一下，已經可以正常的訪問了，訪問的地址為http://localhost:6001/swagger

因為Swashbuckle的默認路徑為http://xxxxxx:xxx/swagger，我這些不知道大家能否看懂是什么意思

 

 展開之后是這個樣子滴，感覺配色還是完全可以接受的，還挺好看的。

 

接下來我們在swagger里增加xml的描述功能，比如控制器里的某個方法的注釋可以在swagger里面顯示出來，這樣有利於前端的同學理解其意義

首先我們在DogService的控制器中的Test()方法加上注釋

 

在DogService項目上點擊右鍵，點擊屬性，點擊生成，把xml文檔文件前面的✔打上並保存

那個xml的文件路徑是可以自己修改的，這里我直接使用默認的路徑了

 

配置完畢之后，我們把DogService項目重新生成一下，然后通過dotnet命令運行起來

看到上圖中出現了一個DogService.xml的文件，對咯，這個就是給swagger使用的說明描述文件，我們可以看一下里面是什么內容

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>DogService</name>
    </assembly>
    <members>
        <member name="M:DogService.Controllers.ValuesController.Test">
            <summary>
            尋找一只狗
            </summary>
            <returns></returns>
        </member>
    </members>
</doc>

接下來我們需要在startup的ConfigureServices方法中增加一個配置，那個DogService.xml就是在生成之后的那個xml文件名字，這里一定要對應上，否則會提示你找不到這個xml文件

 

 

接下來，我們通過地址來訪問一下，看看效果。

我們通過上圖看到，test方法的注釋已經可以在swagger里正常顯示了

 

然后CatService的swagger配置就不在描述了，跟DogService是一模一樣的

 

在下一個文章里會介紹一下如果在Ocelot中集成swagger的方式，謝謝大家！