通过Swashbukle给DotNet Core Web API 增加自动文档功能

　　DotNet Core Web API给开发者提供了一个很好的框架来开发Restful的API。那么这些API接口该如何管理起来呢？Swagger是一个很好的选择，Swagger不需要开发者额外去维护接口文档，只要开发者的接口遵循Restful的规范，Swagger就会根据API接口生成文档。 

　　对于前后端分离的开发模式，前后端开发者一般会先定义好接口，然后各自独立开发，后端开发者可以使用Swagger很快的生成没有业务逻辑的接口文档，接口返回的是Mock Data，这样前端开发人员就可以更早的开始调用接口，只要关注Swagger的接口文档是否有发生变化，尽早的发现错误，避免了前后端最后集成时，出现大问题。 

　　后端开发者使用Swagger也可以很好的调试，Swagger提供了一个简单的UI界面，可以模拟简单的post，get，put 。功能没有curl或者postman强大，但是优势在于简单快捷，只要在swagger文档界面点点就可以。 

　　这里要介绍的就是：Dotnet Core 2.0 下面的 Swashbukle.AspNetCore

　　Github地址： https://github.com/domaindrivendev/Swashbuckle.AspNetCore

　　这篇文章的源码：dotnet-core-sample 的 sample1中 　　

　　1.首先创建一个dotnet core web api 项目,通过命令行输入

dotnet new webapi -name sample1

　　 2. 然后下载Swashbuckle AspNetCore

dotnet add package Swashbuckle.AspNetCore

 　　在VS 2017下面，通过 工具 -> Nuget 包管理器 -> 程序包管理控制台， 运行

Install-Package Swashbuckle.AspNetCore

 注意：这里运行的是Install-Package Swashbuckle.AspNetCore 不是Install-Package Swashbuckle

　　3.在Startup.cs文件中，引入Swashbuckle 

using Swashbuckle.AspNetCore.Swagger;

　　

　　4.在Startup.cs文件中的ConfigureService方法中注册Swagger Generator

       public void ConfigureServices(IServiceCollection services)
       {
           services.AddMvc();
           services.AddSwaggerGen(config =>

           {
               config.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" });
           });
       }

 

　　5. 在Configure方法中添加Swagger的中间件 

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

           }
           app.UseMvc();

           app.UseSwagger();
       }

 

　　6. 最后执行一下dotnet run或者F5，就可以直接运行项目了

dotnet run

 

默认情况下，可以通过http://localhost:5000/swagger/ 访问API接口文档

 


 

注意：要自动生成文档，对应Controller下的接口必须显示的指定用那种Http请求方式，POST，GET，PUT，DELETE 

Swagger运行起来后，有时候需要针对项目进行一些简单的配置：

除了前面提到的 new Info { Title = "My API", Version = "v1" }，Swashbukle还可以配置其他信息，具体可以参见OpenAPI Specification.

config.SwaggerDoc("v1",    new Info
   {
       Title = "My API - V1",
       Version = "v1",
       Description = "A sample API to demo Swashbuckle",
       TermsOfService = "Knock yourself out",
       Contact = new Contact
       {
           Name = "Joe Developer",
           Email = "joe.developer@tempuri.org"
       },
       License = new License
       {
           Name = "Apache 2.0",
           Url = "http://www.apache.org/licenses/LICENSE-2.0.html"
       }
   }
)

最后，如果要配置多个swagger文档，需要通知添加swagger generator和endpoint

config.SwaggerDoc("v2", new Info { Title = "My API - V2", Version = "v2" });
config.SwaggerEndpoint("/swagger/v2/swagger.json", "My API V2");

原文地址：http://www.cnblogs.com/unclechan/p/7508011.html

.NET社区新闻，深度好文，微信中搜索dotNET跨平台或扫描二维码关注