Swagger 教學
Program.cs
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(options =>
{
// Authorization
options.AddSecurityDefinition("SeeGo",
new OpenApiSecurityScheme
{
Name = "Authorization",
Type = SecuritySchemeType.ApiKey,
Scheme = "SeeGo",
BearerFormat = "JWT",
In = ParameterLocation.Header,
Description = "JWT Authorization"
});
options.AddSecurityRequirement(
new OpenApiSecurityRequirement
{
{
new OpenApiSecurityScheme
{
Reference = new OpenApiReference
{
Type = ReferenceType.SecurityScheme,
Id = "SeeGo"
}
},
new string[] {}
}
});
// 版本資訊
options.SwaggerDoc("v1", new OpenApiInfo
{
Version = "v1",
Title = "SeeGo API",
Description = "An ASP.NET Core Web API for SeeGo",
});
// using System.Reflection;
var xmlFilename = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
options.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, xmlFilename));
});
找到builder.Services.AddEndpointsApiExplorer();
然後加上上面的程式碼
builder.Services.AddSwaggerGe裡面一定要加上
var xmlFilename = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
options.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, xmlFilename));
然後在下面一堆app.的地方要加上
// Configure the HTTP request pipeline.
//if (app.Environment.IsDevelopment())
//{
// app.UseSwagger();
// app.UseSwaggerUI();
//}
app.UseSwagger();
app.UseSwaggerUI();
註解的部分是在開發環境的時候用的
專案檔
在專案檔點右鍵編輯專案檔
<PropertyGroup>
<TargetFramework>net6.0</TargetFramework>
<Nullable>enable</Nullable>
<ImplicitUsings>enable</ImplicitUsings>
<GenerateDocumentationFile>true</GenerateDocumentationFile>
<NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>
在裡面加上
<GenerateDocumentationFile>true</GenerateDocumentationFile>
<NoWarn>$(NoWarn);1591</NoWarn>
XML
在專案底下新增Docs資料夾 在資料夾裡創一個類似XXXAPIDocs.xml的檔案
裡面放以下這樣的結構
<doc>
<members>
<member name="Login">
</member>
<member name="驗證電子信箱">
</member>
</members>
</doc>
接著就可以開始編寫 比如這樣
<member name=“驗證電子信箱”> <summary> [已完成]驗證電子信箱（VType=1註冊、VType=2忘記密碼、VType=3重新發送驗證碼） </summary> <remarks> <para> 發送包含驗證碼的電子郵件的 API。 </para> <para> 使用VType來切換不同情境（1: 註冊 2: 忘記密碼 3: 重新發送驗證碼）。 </para> </remarks> <param name=“ReqVerifyEmail”></param> <returns>返回包含Token的回應。</returns> <response code=“200”> <remarks> “msg”: “4QP4mGh06iGQD5fdSimTuI0UsY9IG08PdEI14HslhvM=” </remarks> </response> <response code=“400”> <remarks> 錯誤訊息: “VType輸入錯誤！”、“查無此帳號！”、“帳號重複註冊！”、“您的驗證已超過10分鐘！” </remarks> </response> </member>onse> </member>
ReqData.cs
如果有required data，可以直接在此註解，這些內容都會出現在schema內，方便前端開發人員閱讀，並且example的值還會自動帶入測試時的預設值，讓測試更加方便。
/// <summary>寄驗證信需要的資料</summary>
public class ReqVerifyEmail
{
/// <summary>電子郵件</summary>
/// <example>test@gmail.com</example>
public string Email { get; set; }
/// <summary>驗證類型(1: 註冊 2: 忘記密碼 3: 重新發送驗證碼)</summary>
/// <example>1</example>
public int VType { get; set; }
}
ResData.cs
response data也可註解。
/// <summary>通用的 API 回應模型</summary>
public class ResData
{
/// <summary>回應狀態，例如 "OK"、"Err"</summary>
/// <example>(狀態碼)</example>
public string State { get; set; }
/// <summary>訊息內容或 Token，例如"成功"、"(錯誤訊息)"</summary>
/// <example>(訊息)</example>
public string Msg { get; set; }
}
XXXController.cs
可以使用以下方式連結到XML文件
/// <include file='Docs/AccountAPIDocs.xml' path='doc/members/member[@name="驗證電子信箱"]/*'/>
[HttpPost("VerifyEmail")]
[Produces("application/json")]
[ProducesResponseType(StatusCodes.Status200OK, Type = typeof(ResData))]
[ProducesResponseType(StatusCodes.Status400BadRequest, Type = typeof(ResData))]
file裡面放XML檔案路徑
path則是依據XML檔案的結構，name的名稱是對應的。
<member name="驗證電子信箱">
path='doc/members/member[@name="驗證電子信箱"]/*'
[ProducesResponseType(StatusCodes.Status200OK, Type = typeof(ResData))]可以指定回應的類型，ResData.cs內註解的內容同樣會出現在response的schema內。
參考
開始使用 Swashbuckle 及 ASP.NET Core | Microsoft Learn