网站用cms,2022房地产行业现状及前景,wordpress连续获取下一文章,网站建设行业新闻Swagger这个优秀的开源项目相信大家都用过#xff0c;不多介绍了#xff0c;这里简单记录一下使用过程。开源地址#xff1a;https://github.com/domaindrivendev/Swashbuckle.AspNetCore在项目中添加组件Install-Package Swashbuckle.AspNetCore下面用最少的代码完成接入不多介绍了这里简单记录一下使用过程。开源地址https://github.com/domaindrivendev/Swashbuckle.AspNetCore在项目中添加组件Install-Package Swashbuckle.AspNetCore
下面用最少的代码完成接入在Startup启动项中配置。public void ConfigureServices(IServiceCollection services)
{...services.AddSwaggerGen(x {x.SwaggerDoc(v1, new Microsoft.OpenApi.Models.OpenApiInfo{Version v1.0.0,Title Api,Description XXX Api});});...
}
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{...app.UseSwagger();app.UseSwaggerUI(c {c.SwaggerEndpoint(/swagger/v1/swagger.json, API);});...
}
这样便完成了swagger会自动发现我们在controller中写的api默认打开页面为~/swagger。同时还可以让其支持分组展示只需要像上面一样配置多个节点信息接口如下面代码services.AddSwaggerGen(options
{options.SwaggerDoc(v1, new Microsoft.OpenApi.Models.OpenApiInfo{Version v1.0.0,Title Api1,Description XXX Api1});options.SwaggerDoc(v2, new Microsoft.OpenApi.Models.OpenApiInfo{Version v1.0.0,Title Api2,Description XXX Api2});
});
app.UseSwaggerUI(c
{c.SwaggerEndpoint(/swagger/v1/swagger.json, API1);c.SwaggerEndpoint(/swagger/v2/swagger.json, API2);
});
如果在控制器中不指定接口的分组名称那么每个分组都会显示这个接口如果需要单独指定可以使用特性[ApiExplorerSettings(GroupName v1)]这样。如果想要显示接口的注释模型的注释等信息需要我们将对应的项目设置输出XML文件并在代码中使用options.IncludeXmlComments(xxx.xml)即可。下面来说一下swagger的一些其它功能当我们接口开启了JWT方式的认证默认swagger是不支持的需要我们手动去适配一下。需要额外添加一个组件Install-Package Swashbuckle.AspNetCore.Filters
context.Services.AddSwaggerGen(options
{...var security new OpenApiSecurityScheme{Description bplease enter codeBearer {Token}/code for authentication./b,Name Authorization,In ParameterLocation.Header,Type SecuritySchemeType.ApiKey};options.AddSecurityDefinition(oauth2, security);options.AddSecurityRequirement(new OpenApiSecurityRequirement { { security, null } });options.OperationFilterAddResponseHeadersFilter();options.OperationFilterAppendAuthorizeToSummaryOperationFilter();options.OperationFilterSecurityRequirementsOperationFilter();
});
现在UI界面便会出现小绿锁这样就可以很方便的在swagger上进行需要授权的接口调试工作了。同时swagger还支持一些高级操作比如自定义UI界面、注入JS、CSS代码因为这个用的不是很多实际要用的时候可以去GitHub查看使用方法。// Customize index.html
app.UseSwaggerUI(c
{c.IndexStream () GetType().Assembly.GetManifestResourceStream(CustomUIIndex.Swagger.index.html);
});// Inject Custom CSS
app.UseSwaggerUI(c
{...c.InjectStylesheet(/swagger-ui/custom.css);
}
这里还要说一下swagger的过滤器我们可以实现IDocumentFilter接口来实现自定义的接口排序个性化接口描述以及各种骚操作比如我们想要隐藏某些API当然隐藏API可以使用.NET Core 的特性[ApiExplorerSettings(IgnoreApi true)]实现。这里隐藏是指不在swaggerUI中显示实际接口还是存在的。public class SwaggerDocumentFilter : IDocumentFilter
{public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context){var tags new ListOpenApiTag{new OpenApiTag {Name Authentication,Description Authentication,ExternalDocs new OpenApiExternalDocs { Description Authentication }},new OpenApiTag {Name Localization,Description Localization,ExternalDocs new OpenApiExternalDocs { Description Localization }}};swaggerDoc.Tags tags.OrderBy(x x.Name).ToList();var apis context.ApiDescriptions.Where(x x.RelativePath.Contains(abp));if (apis.Any()){foreach (var item in apis){swaggerDoc.Paths.Remove(/ item.RelativePath);}}}
}
上面这段代码使用了abp框架搭建的项目abp默认实现了一部分接口如果我们不需要的话就可以使用上面的方式进行过滤。最后一点如果我们用了第三方框架像上面说的abp或者使用了动态API生成的组件比如Plus.AutoApi想要在swagger中显示出api接口需要添加下面这句代码。context.Services.AddSwaggerGen(options
{...options.DocInclusionPredicate((docName, description) true);...
});
swagger推出的同时还推出了一款工具ReDoc下面也简单介绍一下。ReDoc和swagger比较类似只是一个文档展示工具不提供接口调试的功能。他们的使用方式基本一致先在项目中添加一下组件Install-Package Swashbuckle.AspNetCore.ReDoc
在OnApplicationInitialization中直接添加一句配置即可。app.UseReDoc();
它支持多种参数选项可以自行查看默认打开页面为~/api-docs下面是他的UI界面。
