Swagger / OpenAPI Specification 內嵌外部 Markdown 文件並用 Redocly 轉成靜態 html

我只是想要內嵌 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

 

範例位置

sample.dotblog/WebAPI/Swagger/Redoc at 93801035a1a981ce5dcf3faeb14996c41b50253a · yaochangyu/sample.dotblog

若有謬誤,煩請告知,新手發帖請多包涵


Microsoft MVP Award 2010~2017 C# 第四季
Microsoft MVP Award 2018~2022 .NET

Image result for microsoft+mvp+logo