我只是想要內嵌 Markdown 到 OpenAPI.yaml 裡,並且用 Redoc 產生出靜態檔案,就卡了一個下午,這沒有筆記一下接下來一定會忘記的,參考連結在這裡 Embed Markdown in Redocly API reference docs
開發環境
- Windows 11 Home
- Rider 2024.2.7
Redocly CLI
安裝
npm install @redocly/cli --global
產生文檔
從官方連結下載 petstore.yaml 範例,另存檔案後執行以下語法
redocly build-docs petstore.yaml --output petstore.html
產生好的 petstore.html 如下圖
redocly preview-docs
或是建立一個本機伺服器來載入 petstore.yaml 檔案
redocly preview-docs petstore.yaml
訪問 http://127.0.0.1:8080,執行結果如下,只要 petstore.yaml 有任何異動,就會立即更新結果
編寫 Markdown
OpenAPI 也支援 Markdown 的語法,在 petstore.yaml 的 description 節點加入 Markdown 的結構,如下所示
openapi: "3.0.0"
info:
version: 1.0.0
title: Swagger Petstore
license:
name: MIT
description: |
# Web API
This is the API documentation.
## Features
- Item1
- Item2
1. Number1
2. Number2
servers:
- url: http://petstore.swagger.io/v1
執行結果如下:
內嵌外部 md 檔
除了可以在 yaml 編輯 Markdown 以外,也可以載入外部檔案 Markdown,把以下內容另存為 description.md
# Web API
This is the API documentation.
## Features
- Item1
- Item2
1. Number1
2. Number2
在 petstore.yaml 使用 $ref: ./description.md
openapi: "3.0.0"
info:
version: 1.0.0
title: Swagger Petstore
license:
name: MIT
description:
$ref: ./description.md
servers:
- url: http://petstore.swagger.io/v1
這裡要注意一下檔案路徑,本篇範例 petstore.yaml、description.md 都在同一個資料夾內
使用 $ref: ./description.md 也無法使用 OpenAPI (Swagger) Editor 外掛預覽 OpenAPI
範例位置
若有謬誤,煩請告知,新手發帖請多包涵
Microsoft MVP Award 2010~2017 C# 第四季
Microsoft MVP Award 2018~2022 .NET