一、Swagger介紹
簡單來說swagger是一款WebAPI的接口管理幫助文檔，並且可以直接進行接口測試
我們來看一下官網介紹 https://swagger.io
Swagger is a powerful yet easy-to-use suite of API developer tools for teams and individuals, enabling development across the entire API lifecycle, from design and documentation, to test and deployment.
Swagger 是一套功能強大且易於使用的 API 開發人員工具套件，適用於團隊和個人，支持從設計和文檔到測試和部署的整個 API 生命周期的開發。
Swagger consists of a mix of open source, free and commercially available tools that allow anyone, from technical engineers to street smart product managers to build amazing APIs that everyone loves.
Swagger 包含開源、免費和商用工具的組合，允許任何人，從技術工程師到街頭智能產品經理，構建每個人都喜歡的令人驚嘆的 API。
Swagger is built by SmartBear Software, the leader in software quality tools for teams. SmartBear is behind some of the biggest names in the software space, including Swagger, SoapUI and QAComplete.
Swagger 由 SmartBear Software 構建，SmartBear Software 是團隊軟件質量工具的領導者。SmartBear 是軟件領域一些大牌的幕后推手，包括 Swagger、SoapUI 和 QAComplete。
二、.Net中集成Swagger
1. NuGet包安裝Swashbuckle
搜索Swashbuckle,下載並安裝(我的是5.6.0)
安裝完之后會生成Swagger文件夾和App_Start下的SwaggerConfig文件
2. 修改SwaggerConfig
里面有很多方法被注釋掉，也基本都用不上，所以我就刪了，只保留了常用的方法
/// <summary>
/// Swagger Config
/// </summary>
public class SwaggerConfig
{
/// <summary>
/// Swagger Register
/// </summary>
public static void Register()
{
GlobalConfiguration.Configuration
.EnableSwagger(c =>
{
//文檔抬頭說明
c.SingleApiVersion("v1", "").Description("請先登錄獲取token放置api_key輸入框中，作為header參數認證憑據");
//文檔接口、參數說明等
c.IncludeXmlComments(GetXmlCommentsPath());
})
.EnableSwaggerUi(c =>
{
//默認頁面替換，為什么要替換，因為原生的不好用（你可以注釋掉這行代碼體驗一下）
c.CustomAsset("index", typeof(SwaggerConfig).Assembly, "PLM.WebAPI.Swagger.index.html");
});
}
private static string GetXmlCommentsPath()
{
return $"{AppDomain.CurrentDomain.BaseDirectory}/bin/PLM.WebAPI.xml";
}
}
3. 配置XML注釋文檔
需要在項目屬性中勾選XML文檔
4. index.html替換
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>PLM WebApi</title>
<link rel="icon" type="image/png" href="images/logo_small-png.png" sizes="32x32" />
<link href="css/typography-css.css" media="screen" rel="stylesheet" type="text/css" />
<link href="css/reset-css.css" media="screen" rel="stylesheet" type="text/css" />
<link href="css/screen-css.css" media="screen" rel="stylesheet" type="text/css" />
<link href="css/reset-css.css" media="print" rel="stylesheet" type="text/css" />
<link href="css/print-css.css" media="print" rel="stylesheet" type="text/css" />
<script src="lib/object-assign-pollyfill-js.js" type="text/javascript"></script>
<script src="lib/jquery-1-8-0-min-js.js" type="text/javascript"></script>
<script src="lib/jquery-slideto-min-js.js" type="text/javascript"></script>
<script src="lib/jquery-wiggle-min-js.js" type="text/javascript"></script>
<script src="lib/jquery-ba-bbq-min-js.js" type="text/javascript"></script>
<script src="lib/handlebars-4-0-5-js.js" type="text/javascript"></script>
<script src="lib/lodash-min-js.js" type="text/javascript"></script>
<script src="lib/backbone-min-js.js" type="text/javascript"></script>
<script src="swagger-ui-min-js.js" type="text/javascript"></script>
<script src="lib/highlight-9-1-0-pack-js.js" type="text/javascript"></script>
<script src="lib/highlight-9-1-0-pack_extended-js.js" type="text/javascript"></script>
<script src="lib/jsoneditor-min-js.js" type="text/javascript"></script>
<script src="lib/marked-js.js" type="text/javascript"></script>
<script src="lib/swagger-oauth-js.js" type="text/javascript"></script>
<script type="text/javascript">
$(function () {
window.swaggerUi = new SwaggerUi({
url: window.location.origin + "/Swagger/docs/v1",
dom_id: "swagger-ui-container",
supportedSubmitMethods: ["get", "post"],
onComplete: function (swaggerApi) {
window.swaggerApi = swaggerApi;
},
onFailure: function () {
console.log("Unable to Load SwaggerUI");
},
jsonEditor: true,//表單編輯器
showRequestHeaders: false,//顯示請求頭
validatorUrl: null,//json驗證
docExpansion: 'none'//是否展開 none list full
});
function addApiKeyAuthorization() {
var key = $("#input_apiKey").val();
if (key && key.trim() !== "") {
var apiKeyAuth = new SwaggerClient.ApiKeyAuthorization("Authorization", key, "header");
window.swaggerUi.api.clientAuthorizations.add("api_key", apiKeyAuth);
}
}
$("#input_apiKey").change(addApiKeyAuthorization);
window.swaggerUi.load();
});
</script>
</head>
<body class="swagger-section">
<div id="header">
<div class="swagger-ui-wrap">
<a id="logo" href="javascript:;"><span class="logo__title">PLM WebApi</span></a>
<form id="api_selector">
<div class="input">
<input placeholder="api_key" id="input_apiKey" name="apiKey" type="text" autocomplete="off" />
</div>
</form>
</div>
</div>
<div id="swagger-ui-container" class="swagger-ui-wrap"></div>
</body>
</html>
5. 使用方法
運行項目之后，在后面加上/swagger即可，如https://localhost:8099/swagger
你可以設置默認頁，默認啟動之后打開Swagger文檔主頁
三、.Net Core中集成Swagger
PS：.Net5 以上自帶集成Swagger，直接跳過集成，查看JWT使用即可
1. NuGet包安裝Swashbuckle.AspNetCore
搜索Swashbuckle.AspNetCore，下載並安裝(我的是5.6.3)
2. 配置Startup
在ConfigureServices方法中添加代碼
services.AddSwaggerGen(c =>
{
//獲取注釋文檔路徑 bin\Debug\net5.0\NetCoreApiDemo.xml
var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
//顯示方法注釋
c.IncludeXmlComments(xmlPath, true);
c.SwaggerDoc("v1", new OpenApiInfo { Title = "NetCoreApi", Version = "v1" });
});
在 Configure 方法中添加代碼
盡量靠前，添加在if (env.IsDevelopment()){}后面即可
app.UseSwagger();
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "NetCoreApiDemo v1");
c.DocExpansion(Swashbuckle.AspNetCore.SwaggerUI.DocExpansion.None); //折疊Api
c.DefaultModelsExpandDepth(-1); //去除Model 顯示
});
3. 設置swagger為起始頁
在Properties文件夾中的launchSettings.json中更改launchUrl為swagger即可
四、JWT配合使用
如果用到JWT授權，請先參考文章 https://www.cnblogs.com/dennisdong/p/15719005.html 弄好JWT相關配置
1. .NET中使用
將獲取的Jwt Token 放置右上角的文本框中即可
2. .NET Core中使用
在Startup的ConfigureServices方法中找到services.AddSwaggerGen並添加配置
services.AddSwaggerGen(c =>
{
//添加Jwt驗證設置,添加請求頭信息
c.AddSecurityRequirement(new OpenApiSecurityRequirement
{
{
new OpenApiSecurityScheme
{
Reference = new OpenApiReference
{
Id = "Bearer",
Type = ReferenceType.SecurityScheme
}
},
new List<string>()
}
});
//放置接口Auth授權按鈕
c.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
{
Description = "Value Bearer {token}",
Name = "Authorization",//jwt默認的參數名稱
In = ParameterLocation.Header,//jwt默認存放Authorization信息的位置(請求頭中)
Type = SecuritySchemeType.ApiKey
});
});
點擊授權按鈕，把JWT Token 填入文本框中點擊登錄即可
PS： 格式為 Bearer + 空格 + Token
五、跨域問題
請參考文章 https://www.cnblogs.com/dennisdong/p/15719873.html