Swagger UI in AspNetCore WebAPI

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

  

installation

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

 

 或者使用命令行： 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进行处理。
addsecuritydefinition和addsecurityrequirement：用于给swagger添加验证的部分。
includexmlcomments：为openapi提供注释内容的xml，需要在ide里面配置生成对应的xml文件。（当vs中使用生成xml文档文件这个功能的时候，如果有方法没有添加注释，vs会有提示，如果要避免这个提示，可以在下图中的suppress warnings中把1591禁掉。）

 

 

 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 }