Api文件

大家是不是在开发时还要想着要如何提供技术文件，尤其是在忙着开发Api还没有余力时还要一边撰写文件，不过这些都还好，最麻烦的时当Api更新时文件没更新更让人头痛，所以今天跟大家分享一下如何自动产生Api文件。

本文同步放置於此

Swashbuckle

「前辈，主管要我们提供Api的技术文件给厂商，你有没有写过啊。」
今天大头因为主管跟厂商开会时厂商有提到说没有Api文件不知道怎麽开发，这时大头就跟老K请教说该如何写Api文件。
「你在写Api时有没有写注解阿。」
听到大头的问题後老K跟问了这件事，由於问的问题跟回答的内容似乎没有关系所以大头一脸疑惑的样子，这时小光走过来。
「前辈，大头前备有交代要记得再Api的Action要写注解。」
听到小光的回答後老K点点头，不过大头更疑惑了。
「不过前辈我们怎麽把注解提供给厂商阿。」
这时大头耐不住性子就把他的问题问了出来。
「那你跟小光去研究Swashbuckle.AspNetCore吧，他事可以帮你产生Api文件的套件，你看一看吧这样就不用另外花时间写文件了。」
所以小光就跟大头开始研究Swashbuckle。

环境设定

一如往昔的我们先安装所需的套件，这时一样输入以下指令即可。

dotnet add package Swashbuckle.AspNetCore

如此他会一并安装以下相依的套件，所以可以不用特别去安装他。

• Swashbuckle.AspNetCore.Swagger
• Swashbuckle.AspNetCore.SwaggerGen
• Swashbuckle.AspNetCore.SwaggerUI

安装完成之後开始要设定使用Swashbuckle在我们的专案内了。

设定Api文件

首先我们先设定让我们的dotnetcore可以使用Swashbuckle的功能，首先在Startup.ConfigureServices加入以下内容。

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("版号", new OpenApiInfo { Title = "专案名称", Version = "版号" });
});

再来是在再Startup.Configure加入以下内容设定middleware

app.UseSwagger();
app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/版号/swagger.json", "专案名称 版号"));

设定完後执行专案进入到root/swagger/index.html就可以看到预设的Swagger的画面了，不过相信大家这时应该还没有看到说明内容。

Swagger没有说明文字

加入说明文件

这部分要让我们的Swagger内有说明内容，不过在这之前先跟大家介绍如何产生说明文件，首先在我们的程序码中要有summary的标签，如下所示。

/// <summary>
/// 取得温度
/// </summary>
/// <returns>温度的列举</returns>
[HttpGet]
public IEnumerable<WeatherForecast> Get()
.
.
.
/// <summary>
/// 依据地区取温度
/// </summary>
/// <param name="zoneId">地区编号</param>
/// <returns>温度列举</returns>
[HttpGet("ByZone")]
public IEnumerable<WeatherForecast> GetByZone(string zoneId)

有了说明资讯之後预设的vscode事不会产出xml档案，所以我们要为专案档.csproj做以下的修改。

  <PropertyGroup>
    <TargetFramework>net5.0</TargetFramework>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
    <NoWarn>1701;1702;1705;1591</NoWarn>
  </PropertyGroup>

简单说明在PropertyGroup里面的TargetFramework下面家两个项目即可。如此在bin资料夹下应该可以看到专案名称.xml这个文件档。在可以产出文件当後我们要设定Swagger来读取我们的文件档做为Api的文件，这部分在services.AddSwaggerGen加入以下内容即可。

// Set the comments path for the Swagger JSON and UI.
var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
c.IncludeXmlComments(xmlPath);

加入之後在画面上应该可以看到说明内容。

Swagger有说明文字

与jwt的协作

之前有过jwt的api在swagger该如何处理呢，所以这边说明一下如何使用swagger跟jwt来协作，首先先在services.AddSwaggerGen加入以下内容。

c.AddSecurityDefinition("Bearer",
    new OpenApiSecurityScheme
    {
        In = ParameterLocation.Header,
        Description = "Please insert JWT with Bearer into field",
        Name = "Authorization",
        Type = SecuritySchemeType.ApiKey
    });

c.AddSecurityRequirement(new OpenApiSecurityRequirement
{
    {
        new OpenApiSecurityScheme
        {
            Reference = new OpenApiReference
            {
                Type = ReferenceType.SecurityScheme,
                Id = "Bearer"
            }
        },
        new string[] { }
    }
});

相信加入之後可以看到以下画面。

Swagger包含JWT

当点击Authorize会出现以下内容。
Swagger的Token输入

最後记得输入的内容要是Bearer (apiKey)的格式。

後记

今天跟大家介绍如何在Api内加入OpenAPI的说明文件，而且Api更新之後文件也会随着跟新，再来还有测试接口不用再特别透过POSTMAN，希望为大家开发时有帮助。