[小菜一碟] 不开放 Swagger 的端点，要怎么提供 Web API 的规格？

在 ASP.NET Core Web API 专案套用了 Swagger 之后，在 Development 环境下预设会有一个 /swagger/index.html 网址来查看 Web API 的规格，但是有些客户因为公司政策的关係，希望关闭 Swagger 端点，改使用静态文件，本篇文章有两个可行的方案提供给大家参考。

Swagger Editor

Swagger Editor 是 Swagger 官方提供的一个线上版编辑器，用来编辑 Swagger 的组态内容，同步呈现 Swagger UI。

我们可以将我们的 swagger.json 档案下载下来，请呼叫端的开发者使用 Swagger Editor 打开，就能以 Swagger UI 的方式浏览 Web API 的规格。

ReDoc CLI

Redoc 是一款 Open Source 的工具，用来从 OpenAPI 定义产生 API 文件。它预设提供三栏式的响应式介面：左侧栏位包含搜寻栏与导览选单；中央栏位显示详细的 API 文件内容；右侧则呈现请求与回应的範例。这样的设计让开发者更方便浏览与理解 API 结构，非常适合用于开发文件的展示与分享。

Redoc 开发团队有提供一个 CLI 工具，叫做 Redocly CLI，可以用来产生完整静态的 Web API 规格文件，它支援的档案格式是 yaml，执行下面指令即可。（从 Swagger UI 下载 yaml 档案的方式在这里）

npx @redocly/cli build-docs swagger.yaml

预设输出的 HTML 档案名称为 redoc-static.html，这个档案就可以直接给呼叫端的开发者参考，画面不输 Swagger UI。

相关资源

C# 指南

ASP.NET 教学

ASP.NET MVC 指引

Azure SQL Database 教学

SQL Server 教学

Xamarin.Forms 教学