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

Swagger UI in AspNetCore WebAPI

程序员文章站 2022-07-01 17:50:07
Swagger其实包含了三个部分,分别是Swagger Editor文档接口编辑器,根据接口文档生成code的Swagger Codegen,以及生成在线文档的Swagger UI。在AspNetCore中通常使用Microsoft封装的Swashbuckle来使用Swagger UI,这是一个As ......

swagger其实包含了三个部分,分别是swagger editor文档接口编辑器,根据接口文档生成code的swagger codegen,以及生成在线文档的swagger ui。
在aspnetcore中通常使用microsoft封装的swashbuckle来使用swagger ui,这是一个aspnetcore的中间件。和其他中间件一样都是分为register和use两个部分。

  

installation


vs中很简单,直接用nuget安装swashbuckle.aspnetcore即可。

 Swagger UI in AspNetCore WebAPI

 或者使用命令行: dotnet add package --version xxx swashbuckle.aspnetcore

 

register


 所有swagger ui注册的configue相关的内容都放在addswaggergen这个方法里面:

namespace microsoft.extensions.dependencyinjection
{
    public static class swaggergenservicecollectionextensions
    {
        public static iservicecollection addswaggergen(this iservicecollection services, action<swaggergenoptions> setupaction = null);
        public static void configureswaggergen(this iservicecollection services, action<swaggergenoptions> setupaction);
    }
}

addswaggergen这个方法主要用户注册中间件的时候添加一些参数,其中重要的有:
swaggerdoc:添加一个swagger document,主要用户存储生成出来的openapi文档。以及一些文档基本信息,如:作者、描述、license等。
xxxfilter:自定义filter,xxx为swagger中的对象,当xxx创建完成后,filter可以定义操作对xxx进行处理。
addsecuritydefinitionaddsecurityrequirement:用于给swagger添加验证的部分。
includexmlcomments:为openapi提供注释内容的xml,需要在ide里面配置生成对应的xml文件。(当vs中使用生成xml文档文件这个功能的时候,如果有方法没有添加注释,vs会有提示,如果要避免这个提示,可以在下图中的suppress warnings中把1591禁掉。)

Swagger UI in AspNetCore WebAPI

 

 

 use

routetemplate:useswagger中配置swagger页面路由信息。
routeprefix:类似sharepoint中的host name,默认为swagger,如果不需要可以设置为“”。
swaggerendpoint:openapi文件的访问url,这个url和routetemplate以及swaggerdoc的name一定要一致,不然就会有page not found的错。
当请求openapi文件的时候,会从swaggerendpoint配置的url中配合routetemplate一起解析document的name。
下面是routetemplate的配置:

1 app.useswagger(option => 
2 {
3   option.routetemplate = string.format("{0}/{1}", prefix, "{documentname}/swagger.json");
4 });

 

解析document name的过程。

 1 private bool requestingswaggerdocument(httprequest request, out string documentname)
 2 {
 3   documentname = null;
 4   if (request.method != "get") return false;
 5 
 6   var routevalues = new routevaluedictionary();
 7   if (!_requestmatcher.trymatch(request.path, routevalues) || !routevalues.containskey("documentname")) return false;
 8 
 9   documentname = routevalues["documentname"].tostring();
10   return true;
11 }