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

       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
      官方文档 :https://docs.microsoft.com/zh-cn/aspnet/core/tutorials/web-api-help-pages-using-swagger?tabs=visual-studio 

  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");

 
这里还有一篇很详细的英文文档: https://elanderson.net/2017/10/swagger-and-swashbuckle-with-asp-net-core-2/ 


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