澳门蒲京网站Asp.Net Core2.0 WebAPI 使用Swagger生成漂亮的接口文档。swagger:API在线文档自动生成框架。

4、点击项目右键属性(勾选生成WebApi.xml文档),为API的在线测试、在线文档提供了一个新的简便的解决方案

1、引用NuGet:

俗的API从出测试开始我们经常借类似Postman、fiddle等等去做接口测试等等工具;Swagger
为API的在线测试、在线文档提供了一个初的省事的化解方案;

     Swashbuckle.AspNetCore.Swagger

 

     Swashbuckle.AspNetCore.SwaggerGen

使用Swagger

NET使用:Swagger-Net

引用NuGet包:Swashbuckle.AspNetCore ;

蕴含如下一些:

Swashbuckle.AspNetCore.Swagger: 一些模实体定义
Swashbuckle.AspNetCore.SwaggerGen: Swagger生成器
Swashbuckle.AspNetCore.SwaggerUI:Swagger UI工具

 

配置:startup.cs

注入swagger:

public void ConfigureServices(IServiceCollection services)
        {
            services.AddMvc();
            // Register the Swagger generator, defining one or more Swagger documents
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" });
            });
        }



public void Configure(IApplicationBuilder app, IHostingEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }
            // Enable middleware to serve generated Swagger as a JSON endpoint.
            app.UseSwagger();

            // Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.), specifying the Swagger JSON endpoint.
            app.UseSwaggerUI(c =>
            {
                c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
            });

            app.UseMvc();
        }

 

 编译运行,下面两只网址:

API文档界面:http://localhost:<random\_port>/swagger

API的restful说明json文件:http://localhost:<random\_port>/swagger/v1/swagger.json

 澳门蒲京网站 1

 

 

 

文档:

官网:https://swagger.io

微软文档:https://docs.microsoft.com/en-us/aspnet/web-api/overview/getting-started-with-aspnet-web-api/creating-api-help-pages

NetCore使用:https://docs.microsoft.com/en-us/aspnet/core/tutorials/web-api-help-pages-using-swagger?tabs=visual-studio

博客资源:http://www.cnblogs.com/dotNETCoreSG/p/aspnetcore_02-09_web-api-help-pages-using-swagger.html

 

澳门蒲京网站 2

  <PackageReference Include="Swashbuckle.AspNetCore.Swagger" Version="1.1.0" />
  <PackageReference Include="Swashbuckle.AspNetCore.SwaggerGen" Version="1.1.0" />

2、Startup文件引用Swagger

 1 services.AddSwaggerGen(options =>
 2 {
 3     options.SwaggerDoc("v1", new Info
 4     {
 5         Version = "v1",
 6         Title = "WebApi文档"
 7     });
 8     options.OperationFilter<ApiHttpHeaderFilter>();
 9 
10     //Determine base path for the application.  
11     var basePath = PlatformServices.Default.Application.ApplicationBasePath;
12     //Set the comments path for the swagger json and ui.  
13     var xmlPath = Path.Combine(basePath, "WebApi.xml");
14     options.IncludeXmlComments(xmlPath);
15 });

1  app.UseSwagger();
2  app.UseSwaggerUI(c =>
3  {
4      c.SwaggerEndpoint("/swagger/v1/swagger.json", "WebApi文档");
5  });

3、对亟待开展授权登录的接口生成对应的文档输入框,如Bearer Token   

 1 using Microsoft.AspNetCore.Authorization;
 2 using Swashbuckle.AspNetCore.Swagger;
 3 using Swashbuckle.AspNetCore.SwaggerGen;
 4 using System.Collections.Generic;
 5 using System.Linq;
 6 
 7 namespace Core.WebApi.Filters
 8 {
 9     /// <summary>
10     /// 对需要进行授权登录的接口生成对应的文档输入框,如Bearer Token
11     /// </summary>
12     public class ApiHttpHeaderFilter : IDocumentFilter, IOperationFilter
13     {
14         /// <summary>
15         /// 
16         /// </summary>
17         /// <param name="operation"></param>
18         /// <param name="context"></param>
19         public void Apply(Operation operation, OperationFilterContext context)
20         {
21             operation.Parameters = operation.Parameters ?? new List<IParameter>();
22             var actionAttributes = context.ApiDescription.ActionAttributes();
23             var allowAnonymous = actionAttributes.Any(a => a.GetType() == typeof(AllowAnonymousAttribute)); // 查询是否过滤权限
24             if (!allowAnonymous)
25             {
26                 operation.Parameters.Add(new BodyParameter
27                 {
28                     Name = "Authorization",
29                     @In = "header",
30                     Description = "access token",
31                     Required = true
32                 });
33             }
34         }
35 
36         /// <summary>
37         /// 
38         /// </summary>
39         /// <param name="swaggerDoc"></param>
40         /// <param name="context"></param>
41         public void Apply(SwaggerDocument swaggerDoc, DocumentFilterContext context)
42         {
43             throw new System.NotImplementedException();
44         }
45     }
46 }

   引用该类:

options.OperationFilter<ApiHttpHeaderFilter>();

4、点击项目右键属性(勾选生成WebApi.xml文档):

澳门蒲京网站 3   

 

效果:

澳门蒲京网站 4