欢迎您访问程序员文章站本站旨在为大家提供分享程序员计算机编程知识!
您现在的位置是: 首页  >  IT编程

asp.net core 3.0中使用swagger的方法与问题

程序员文章站 2022-09-04 13:45:11
intro# 上次更新了 asp.net core 3.0 简单的记录了一下 swagger 的使用,那个项目的 api 比较简单,都是匿名接口不涉及到认证以及 api 版本控制...

intro#

上次更新了 asp.net core 3.0 简单的记录了一下 swagger 的使用,那个项目的 api 比较简单,都是匿名接口不涉及到认证以及 api 版本控制,最近把另外一个 api 项目升级到了 3.0,还是遇到了一些问题,这里单独写一篇文章介绍,避免踩坑。

swagger 基本使用#

swagger 服务注册:

services.addswaggergen(option =>
 {
 option.swaggerdoc("sparktodo", new openapiinfo
 {
  version = "v1",
  title = "sparktodo api",
  description = "api for sparktodo",
  contact = new openapicontact() { name = "weihanli", email = "weihanli@outlook.com" }
 });
 
 // include document file
 option.includexmlcomments(path.combine(appcontext.basedirectory, $"{typeof(startup).assembly.getname().name}.xml"), true);
 });

中间件配置:

//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(option =>
{
 option.swaggerendpoint("/swagger/sparktodo/swagger.json", "sparktodo docs");

 option.routeprefix = string.empty;
 option.documenttitle = "sparktodo api";
});

为 swagger 添加 bearer token 认证#

services.addswaggergen(option =>
{
 // ...

 // add security definitions
 option.addsecuritydefinition("bearer", new openapisecurityscheme()
 {
 description = "please enter into field the word 'bearer' followed by a space and the jwt value",
 name = "authorization",
 in = parameterlocation.header,
 type = securityschemetype.apikey,
 });
 option.addsecurityrequirement(new openapisecurityrequirement
 {
 { new openapisecurityscheme
 {
  reference = new openapireference()
  {
  id = "bearer",
  type = referencetype.securityscheme
  }
 }, array.empty<string>() }
 });
});

支持多个 apiversion#

services.addapiversioning(options =>
 {
 options.assumedefaultversionwhenunspecified = true;
 options.defaultapiversion = apiversion.default;
 options.reportapiversions = true;
 });

services.addswaggergen(option =>
{
 // ...

 option.swaggerdoc("v1", new openapiinfo { version = "v1", title = "api v1" });
 option.swaggerdoc("v2", new openapiinfo { version = "v2", title = "api v2" });

 option.docinclusionpredicate((docname, apidesc) =>
 {
 var versions = apidesc.customattributes()
  .oftype<apiversionattribute>()
  .selectmany(attr => attr.versions);

 return versions.any(v => $"v{v.tostring()}" == docname);
 });

 option.operationfilter<removeversionparameteroperationfilter>();
 option.documentfilter<setversioninpathdocumentfilter>();
});

自定义 api version 相关的 operationfilter:

public class setversioninpathdocumentfilter : idocumentfilter
{
 public void apply(openapidocument swaggerdoc, documentfiltercontext context)
 {
 var updatedpaths = new openapipaths();

 foreach (var entry in swaggerdoc.paths)
 {
  updatedpaths.add(
  entry.key.replace("v{version}", swaggerdoc.info.version),
  entry.value);
 }

 swaggerdoc.paths = updatedpaths;
 }
}

public class removeversionparameteroperationfilter : ioperationfilter
{
 public void apply(openapioperation operation, operationfiltercontext context)
 {
 // remove version parameter from all operations
 var versionparameter = operation.parameters.single(p => p.name == "version");
 operation.parameters.remove(versionparameter);
 }
}

中间件配置:

//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(option =>
{
 option.swaggerendpoint("/swagger/v2/swagger.json", "v2 docs");
 option.swaggerendpoint("/swagger/v1/swagger.json", "v1 docs");

 option.routeprefix = string.empty;
 option.documenttitle = "sparktodo api";
});

最终 swagger 效果

asp.net core 3.0中使用swagger的方法与问题

asp.net core 3.0中使用swagger的方法与问题

memo#

上面的配置来自 https://github.com/weihanli/sparktodo 这个项目,要获取代码可以参考这个项目

reference#

  • https://github.com/domaindrivendev/swashbuckle.aspnetcore/tree/master/test/websites/multipleversions/swagger
  • https://*.com/questions/58197244/swaggerui-with-netcore-3-0-bearer-token-authorization
  • https://github.com/domaindrivendev/swashbuckle.aspnetcore/issues/1295
  • https://github.com/weihanli/sparktodo

总结

以上就是这篇文章的全部内容了,希望本文的内容对大家的学习或者工作具有一定的参考学习价值,谢谢大家对的支持。