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的方式，谢谢大家！