范文檔的 Markdown 結(jié)構(gòu)與 md2html 發(fā)布管道解析)
API設(shè)計(jì)文檔后端【免費(fèi)下載鏈接】OpenAPI-SpecificationThe OpenAPI Specification Repository項(xiàng)目地址https://gitcode.com/gh_mirrors/op/OpenAPI-Specification點(diǎn)擊查看免費(fèi)下載OpenAPI Specification 倉庫OAS不僅定義了 HTTP API 的開放描述標(biāo)準(zhǔn)其自身的規(guī)范正文versions/*.md與src/oas.md也有一套嚴(yán)格的 Markdown 編寫約定并通過 md2html 工具鏈轉(zhuǎn)換為 W3C 風(fēng)格respec 格式的 HTML 規(guī)范文檔。本文以倉庫測試夾具 basic-old.md 為骨架逐層剖析規(guī)范文檔的標(biāo)題層級、版本頭、conformance 章節(jié)、手寫目錄TOC處理、錨點(diǎn)與修訂歷史表格等結(jié)構(gòu)約定并結(jié)合 md2html.test.mjs 測試、spec.config.json 構(gòu)建配置與真實(shí)版本文件說明這套 Markdown 規(guī)范如何被解析、校驗(yàn)并最終發(fā)布。讀完本文你將理解 OAS 規(guī)范文檔的書寫模板、md2html 轉(zhuǎn)換的行為邊界以及如何在本倉庫中驗(yàn)證這些約定。一、為什么規(guī)范正文需要一套 Markdown 約定OpenAPI Specification 的源碼是 Markdown 文檔發(fā)布物則是 HTML。從倉庫結(jié)構(gòu)與構(gòu)建腳本可以推斷出如下鏈路規(guī)范主源文件位于src/oas.md由 spec.config.json 中specSrc與release.sourcePath字段指明每個(gè)已發(fā)布版本在 versions 目錄下對應(yīng)一份X.Y.Z.md如 3.2.1.md、3.1.1.md、3.0.4.md構(gòu)建時(shí)由oai/build-infra包中的 md2html 工具把 Markdown 轉(zhuǎn)成帶 respec 配置的 HTML 規(guī)范頁。正因?yàn)檗D(zhuǎn)換是程序化的規(guī)范正文的 Markdown 結(jié)構(gòu)就必須穩(wěn)定、可預(yù)測哪些標(biāo)題進(jìn)入什么層級、哪個(gè)段落成為 conformance 章節(jié)、手寫目錄如何被丟棄、錨點(diǎn)如何保留全部由約定與代碼共同保證。tests/md2html/fixtures/目錄下的basic-old.md舊輸入與basic-new.md新輸入正是用來鎖定這些行為的樣例而basic-old.html、basic-new.html是它們對應(yīng)的期望輸出。二、從 basic-old.md 解剖規(guī)范文檔的 Markdown 骨架basic-old.md雖然名為 fixture其內(nèi)容正是 OAS 規(guī)范正文的縮微模板。逐行分析可以看到以下幾個(gè)核心結(jié)構(gòu)塊# Heading 1 Text for first chapter #### Version 30.0.1 This is the conformance section ## Table of Contents Will be removed ## Heading 2 Text for first section a nameparameterAllowEmptyValue/Broken anchor ### Heading 3 Text for first subsection Version | Date --------|----------- 30.0.1 | 3001-04-011. 文檔級標(biāo)題H1與版本頭Version 頭第一行# Heading 1對應(yīng)真實(shí)文檔中的# OpenAPI Specification標(biāo)題見 3.0.4.md。緊隨其后的#### Version 30.0.1是版本頭。在真實(shí)倉庫中它的層級并不統(tǒng)一早期版本使用四級標(biāo)題#### Version x.y.z如 3.0.0.md、3.1.0.md從 3.0.4 開始改為二級標(biāo)題## Version 3.0.4見 3.0.4.md、3.1.1.md、3.2.0.md。在輸出 HTML 中該版本頭被轉(zhuǎn)換為section classoverride idconformance一致性章節(jié)見 basic-old.html 第 17–18 行正文This is the conformance section即一致性聲明段。2. 手寫 Table of Contents 會被移除## Table of Contents一節(jié)在目標(biāo) HTML 中完全不存在。原因從 respec 機(jī)制可以理解規(guī)范頁的目錄由 respec 腳本根據(jù)文檔標(biāo)題結(jié)構(gòu)自動生成對應(yīng) HTML 中的#toc因此手寫的 TOC 必須刪除以避免重復(fù)與混亂。這一點(diǎn)在 basic-old.html 與 basic-new.html 中均有驗(yàn)證輸入里的## Table of Contents / Will be removed沒有出現(xiàn)在任何輸出中。3. 錨點(diǎn)anchor的處理a nameparameterAllowEmptyValue/Broken anchor展示了兩種行為該寫法對應(yīng)真實(shí)規(guī)范中為關(guān)鍵概念插入的錨點(diǎn)如3.1.1.md中大量[附錄引用](#appendix-...)依賴這類目標(biāo)錨點(diǎn)在舊格式中它以裸a name.../出現(xiàn)在段落中間HTML 輸出將其轉(zhuǎn)換為span idparameterAllowEmptyValue/span見 basic-old.html 第 21 行而新格式則要求在段內(nèi)使用a namefirst-anchor/a并生成span idfirst-anchor/span見 basic-new.html 第 20 行。4. 修訂歷史表格Revision History文檔末尾的 Markdown 表格是規(guī)范正文的固定收尾結(jié)構(gòu)Version | Date --------|----------- 30.0.1 | 3001-04-01md2html 將其轉(zhuǎn)換為標(biāo)準(zhǔn)的tabletheadtbody結(jié)構(gòu)basic-old.html 第 24–37 行。在真實(shí)規(guī)范中這一節(jié)是## Appendix A: Revision History例如 3.1.1.md 的附錄 A 即修訂歷史。從basic-new.md看新格式還會顯式標(biāo)注## Appendix A: Revision History標(biāo)題使章節(jié)進(jìn)入 respec 的 appendix 語義對應(yīng) basic-new.html 中section classappendix。三、md2html 測試如何鎖定這些行為測試位于 md2html.test.mjs它把fixtures/下每個(gè).md文件作為輸入運(yùn)行oai/build-infra的 md2html.js并將輸出與同名的.html期望文件做嚴(yán)格比對const expected readFileSync(folder entry.name.replace(.md, .html), utf8); const output await md2html( [ --spec-config, spec.config.json, --maintainers, entry.name.replace(.md, .maintainers), entry.name, path/31.0.0.md\npath/30.0.1.md\npath/30.0.0.md, ], folder, ); expect(output.stdout).to.equal(expected);從中可以提取三條關(guān)鍵信息配置來源轉(zhuǎn)換依賴倉庫根目錄的 spec.config.json測試中通過--spec-config傳入該文件定義了slug、shortName、titleName、abstractText、participateLinks、schemas、release等元數(shù)據(jù)fixtures 目錄下另有副本 spec.config.json供測試獨(dú)立運(yùn)行。維護(hù)者列表通過--maintainers傳入對應(yīng)的.maintainers文件例如 basic-old.maintainers 中* Foo Bar foobar會被注入 HTML 的 respec 配置editors字段。版本列表md2html 會收到一份已發(fā)布版本清單path/31.0.0.md\npath/30.0.1.md\npath/30.0.0.md用于生成 respec 配置中的otherLinksOther versions 下拉項(xiàng)。因此在修改規(guī)范 Markdown 時(shí)fixtures目錄既是模板樣本也是回歸測試的基線任何改變標(biāo)題層級、錨點(diǎn)轉(zhuǎn)換或表格渲染的行為都會導(dǎo)致測試失敗。四、真實(shí)版本文件的印證結(jié)構(gòu)與 appendix 體系將 fixture 的骨架與真實(shí)規(guī)范對照可以看到約定在實(shí)際文檔中的規(guī)模版本頭versions/3.0.4.md在標(biāo)題下直接書寫## Version 3.0.4與 BCP 14 關(guān)鍵詞說明MUST / SHOULD / MAY 等隨后是## Introduction、## Definitions等章節(jié)3.0.4.md。Definitions 體系basic-new.md演示了## Definitions下掛### Foo定義條目真實(shí)文檔中### OpenAPI Description、### OpenAPI Document、### Schema均按此模式組織3.0.4.mdmd2html 會為其生成dfn定義標(biāo)記。錨點(diǎn)與交叉引用規(guī)范正文大量使用[See Appendix ...](#appendix-...)形式的內(nèi)部鏈接例如 3.1.1.md 中的附錄 E百分號編碼、附錄 DHeader 與 Cookie 序列化等交叉引用這些目標(biāo)錨點(diǎn)依賴 md2html 對a name/span id的穩(wěn)定轉(zhuǎn)換。修訂歷史真實(shí)文檔以## Appendix A: Revision History收尾3.1.1.md與 fixture 的表格結(jié)構(gòu)一一對應(yīng)。五、代碼塊語言與媒體類型從 basic-new.md 看目標(biāo)輸出能力basic-new.md作為新格式樣例展示了 md2html 對代碼塊語言標(biāo)簽的完整支持面這也是規(guī)范正文中嵌入示例的標(biāo)準(zhǔn)做法語言標(biāo)簽說明樣例內(nèi)容json/yaml最常見的規(guī)范示例如{foo: true}/foo: true配置片段text、無語言、unknown普通文本無高亮text/plain等uriURL 示例含查詢串與片段https://foo.com/bar?bazquxfredwaldo#fragmenturitemplateRFC6570 URI 模板https://foo.com/bar{?baz*,qux}multipartmultipart 媒體類型示例含Content-Type、Content-Location與正文--boundary-example分節(jié)eventstreamSSE 事件流event/data/retry/注釋行addString、addNumber、addJSON事件jsonl/ndjson每行一個(gè) JSON 對象事件流對應(yīng)的行式 JSONjsonseqJSON 文本序列0x1E分隔符 JSON 對象帶時(shí)間戳的兩條日志這些代碼塊在輸出 HTML 中被包裝為pre classnohighlightcode并使用 hljs 主題高亮見 basic-new.html 第 32–103 行。此外basic-new.md還展示了 RFC 引用寫法如[[RFC3986]]、[[RFC9110]]md2html 會將其轉(zhuǎn)換為 bibref 引用或帶 Section 鏈接的引用形式而規(guī)范正文中的 BCP 14 / RFC 關(guān)鍵詞引用見 3.0.4.md即屬于此類。六、Markdown 校驗(yàn)與發(fā)布配置層面的支撐除轉(zhuǎn)換外倉庫還有一整套配置約束規(guī)范正文的書寫質(zhì)量Markdown 風(fēng)格規(guī)則根目錄的 spec.markdownlint.yaml 規(guī)定標(biāo)題必須使用 ATX#前綴風(fēng)格MD003、無序列表必須用*MD004、縮進(jìn) 2 空格MD007、行寬上限 800 字符且表格不參與計(jì)數(shù)MD013、標(biāo)題前后需空行MD022、允許重復(fù)標(biāo)題MD024、允許內(nèi)聯(lián) HTMLMD033——最后一條正是錨點(diǎn)a name能合法存在的原因。校驗(yàn)與構(gòu)建命令package.json 提供validate-markdownoai-spec-validate-markdown、format-markdownoai-spec-format-markdown、buildoai-spec-build、testoai-spec-test等腳本規(guī)范改動的合規(guī)性檢查與構(gòu)建發(fā)布被納入統(tǒng)一命令鏈。發(fā)布期轉(zhuǎn)換根目錄 spec.config.json 的release段說明發(fā)布時(shí)會從src/oas.md生成版本文件并對src/schemas/validation/*.yaml、tests/schema/pass、tests/schema/fail等路徑做 schema 版本號重寫schemaVersionRewrite。也就是說Markdown 結(jié)構(gòu)約定只是 OAS 發(fā)布鏈路的一環(huán)與之配套的還有 schema 與示例的版本同步。七、如何本地查看與驗(yàn)證這套管道查看轉(zhuǎn)換產(chǎn)物fixtures下的.html文件是可直接打開的期望輸出tests/md2html/README.md還說明若要以 respec 格式在本地瀏覽器渲染這些 HTML可執(zhí)行mkdir js cp ../../node_modules/respec/builds/respec-w3c.js js/ echo * js/.gitignore然后本地打開即可倉庫是只讀的這一步驟只涉及本地查看。運(yùn)行測試在倉庫根目錄執(zhí)行yarn test內(nèi)部調(diào)用oai-spec-testmd2html.test.mjs會遍歷 fixtures 中所有.md文件并與.html基線比對任何與本文所述結(jié)構(gòu)約定的偏差都會在此暴露。學(xué)習(xí)完整模板閱讀tests/md2html/fixtures/basic-new.md新格式與versions/3.1.1.md、versions/3.2.1.md等真實(shí)版本正文可以同時(shí)獲得縮微模板與完整成品兩個(gè)視角是編寫或?qū)彶?OAS 規(guī)范文檔的首選參考資料。結(jié)語tests/md2html/fixtures/basic-old.md雖小卻是理解 OpenAPI-Specification 倉庫文檔即代碼、代碼即規(guī)范理念的最佳切入點(diǎn)標(biāo)題層級決定章節(jié)語義Version頭決定 conformance 章節(jié)手寫 TOC 會被丟棄錨點(diǎn)與修訂歷史表格有固定的轉(zhuǎn)換路徑而這一切都被 md2html.test.mjs 與配套的 HTML 基線牢牢鎖定。對任何參與 OAS 規(guī)范維護(hù)或希望自建Markdown 規(guī)范文檔 → respec HTML管道的團(tuán)隊(duì)這套約定與測試模式都值得直接借鑒。贊分享API設(shè)計(jì)文檔后端【免費(fèi)下載鏈接】OpenAPI-SpecificationThe OpenAPI Specification Repository項(xiàng)目地址https://gitcode.com/gh_mirrors/op/OpenAPI-Specification點(diǎn)擊查看免費(fèi)下載相關(guān)推薦OpenAPI Specification 文檔發(fā)布管線剖析md2html 測試夾具與 Respec 渲染機(jī)制OpenAPI Specification 文檔發(fā)布管線剖析md2html 測試夾具與 Respec 渲染機(jī)制 本文以 tests/md2html/fixtuAPI設(shè)計(jì)文檔后端OpenAPI SpecificationSwagger 2.0規(guī)范全解文檔結(jié)構(gòu)、對象定義與機(jī)器可讀 Schema 驗(yàn)證OpenAPI SpecificationSwagger 2.0規(guī)范全解文檔結(jié)構(gòu)、對象定義與機(jī)器可讀 Schema 驗(yàn)證 本篇技術(shù)指南以本倉庫 versiAPI設(shè)計(jì)文檔后端拯救混亂的API文檔OpenAPI-Specification規(guī)范實(shí)戰(zhàn)指南拯救混亂的API文檔OpenAPI Specification規(guī)范實(shí)戰(zhàn)指南 API文檔混亂不堪團(tuán)隊(duì)協(xié)作效率低下OpenAPI SpecificationAPI設(shè)計(jì)文檔后端上一篇Spyder宏錄制開發(fā)者效率革命的終極指南下一篇Semantic Kernel如何約束AI輸出模板工廠與函數(shù)選擇行為拆解創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 OpenAPI-Specification 規(guī)范文檔的 Markdown 結(jié)構(gòu)與 md2html 發(fā)布管道解析
API設(shè)計(jì)文檔后端【免費(fèi)下載鏈接】OpenAPI-SpecificationThe OpenAPI Specification Repository項(xiàng)目地址https://gitcode.com/gh_mirrors/op/OpenAPI-Specification點(diǎn)擊查看免費(fèi)下載OpenAPI Specification 倉庫OAS不僅定義了 HTTP API 的開放描述標(biāo)準(zhǔn)其自身的規(guī)范正文versions/*.md與src/oas.md也有一套嚴(yán)格的 Markdown 編寫約定并通過 md2html 工具鏈轉(zhuǎn)換為 W3C 風(fēng)格respec 格式的 HTML 規(guī)范文檔。本文以倉庫測試夾具 basic-old.md 為骨架逐層剖析規(guī)范文檔的標(biāo)題層級、版本頭、conformance 章節(jié)、手寫目錄TOC處理、錨點(diǎn)與修訂歷史表格等結(jié)構(gòu)約定并結(jié)合 md2html.test.mjs 測試、spec.config.json 構(gòu)建配置與真實(shí)版本文件說明這套 Markdown 規(guī)范如何被解析、校驗(yàn)并最終發(fā)布。讀完本文你將理解 OAS 規(guī)范文檔的書寫模板、md2html 轉(zhuǎn)換的行為邊界以及如何在本倉庫中驗(yàn)證這些約定。一、為什么規(guī)范正文需要一套 Markdown 約定OpenAPI Specification 的源碼是 Markdown 文檔發(fā)布物則是 HTML。從倉庫結(jié)構(gòu)與構(gòu)建腳本可以推斷出如下鏈路規(guī)范主源文件位于src/oas.md由 spec.config.json 中specSrc與release.sourcePath字段指明每個(gè)已發(fā)布版本在 versions 目錄下對應(yīng)一份X.Y.Z.md如 3.2.1.md、3.1.1.md、3.0.4.md構(gòu)建時(shí)由oai/build-infra包中的 md2html 工具把 Markdown 轉(zhuǎn)成帶 respec 配置的 HTML 規(guī)范頁。正因?yàn)檗D(zhuǎn)換是程序化的規(guī)范正文的 Markdown 結(jié)構(gòu)就必須穩(wěn)定、可預(yù)測哪些標(biāo)題進(jìn)入什么層級、哪個(gè)段落成為 conformance 章節(jié)、手寫目錄如何被丟棄、錨點(diǎn)如何保留全部由約定與代碼共同保證。tests/md2html/fixtures/目錄下的basic-old.md舊輸入與basic-new.md新輸入正是用來鎖定這些行為的樣例而basic-old.html、basic-new.html是它們對應(yīng)的期望輸出。二、從 basic-old.md 解剖規(guī)范文檔的 Markdown 骨架basic-old.md雖然名為 fixture其內(nèi)容正是 OAS 規(guī)范正文的縮微模板。逐行分析可以看到以下幾個(gè)核心結(jié)構(gòu)塊# Heading 1 Text for first chapter #### Version 30.0.1 This is the conformance section ## Table of Contents Will be removed ## Heading 2 Text for first section a nameparameterAllowEmptyValue/Broken anchor ### Heading 3 Text for first subsection Version | Date --------|----------- 30.0.1 | 3001-04-011. 文檔級標(biāo)題H1與版本頭Version 頭第一行# Heading 1對應(yīng)真實(shí)文檔中的# OpenAPI Specification標(biāo)題見 3.0.4.md。緊隨其后的#### Version 30.0.1是版本頭。在真實(shí)倉庫中它的層級并不統(tǒng)一早期版本使用四級標(biāo)題#### Version x.y.z如 3.0.0.md、3.1.0.md從 3.0.4 開始改為二級標(biāo)題## Version 3.0.4見 3.0.4.md、3.1.1.md、3.2.0.md。在輸出 HTML 中該版本頭被轉(zhuǎn)換為section classoverride idconformance一致性章節(jié)見 basic-old.html 第 17–18 行正文This is the conformance section即一致性聲明段。2. 手寫 Table of Contents 會被移除## Table of Contents一節(jié)在目標(biāo) HTML 中完全不存在。原因從 respec 機(jī)制可以理解規(guī)范頁的目錄由 respec 腳本根據(jù)文檔標(biāo)題結(jié)構(gòu)自動生成對應(yīng) HTML 中的#toc因此手寫的 TOC 必須刪除以避免重復(fù)與混亂。這一點(diǎn)在 basic-old.html 與 basic-new.html 中均有驗(yàn)證輸入里的## Table of Contents / Will be removed沒有出現(xiàn)在任何輸出中。3. 錨點(diǎn)anchor的處理a nameparameterAllowEmptyValue/Broken anchor展示了兩種行為該寫法對應(yīng)真實(shí)規(guī)范中為關(guān)鍵概念插入的錨點(diǎn)如3.1.1.md中大量[附錄引用](#appendix-...)依賴這類目標(biāo)錨點(diǎn)在舊格式中它以裸a name.../出現(xiàn)在段落中間HTML 輸出將其轉(zhuǎn)換為span idparameterAllowEmptyValue/span見 basic-old.html 第 21 行而新格式則要求在段內(nèi)使用a namefirst-anchor/a并生成span idfirst-anchor/span見 basic-new.html 第 20 行。4. 修訂歷史表格Revision History文檔末尾的 Markdown 表格是規(guī)范正文的固定收尾結(jié)構(gòu)Version | Date --------|----------- 30.0.1 | 3001-04-01md2html 將其轉(zhuǎn)換為標(biāo)準(zhǔn)的tabletheadtbody結(jié)構(gòu)basic-old.html 第 24–37 行。在真實(shí)規(guī)范中這一節(jié)是## Appendix A: Revision History例如 3.1.1.md 的附錄 A 即修訂歷史。從basic-new.md看新格式還會顯式標(biāo)注## Appendix A: Revision History標(biāo)題使章節(jié)進(jìn)入 respec 的 appendix 語義對應(yīng) basic-new.html 中section classappendix。三、md2html 測試如何鎖定這些行為測試位于 md2html.test.mjs它把fixtures/下每個(gè).md文件作為輸入運(yùn)行oai/build-infra的 md2html.js并將輸出與同名的.html期望文件做嚴(yán)格比對const expected readFileSync(folder entry.name.replace(.md, .html), utf8); const output await md2html( [ --spec-config, spec.config.json, --maintainers, entry.name.replace(.md, .maintainers), entry.name, path/31.0.0.md\npath/30.0.1.md\npath/30.0.0.md, ], folder, ); expect(output.stdout).to.equal(expected);從中可以提取三條關(guān)鍵信息配置來源轉(zhuǎn)換依賴倉庫根目錄的 spec.config.json測試中通過--spec-config傳入該文件定義了slug、shortName、titleName、abstractText、participateLinks、schemas、release等元數(shù)據(jù)fixtures 目錄下另有副本 spec.config.json供測試獨(dú)立運(yùn)行。維護(hù)者列表通過--maintainers傳入對應(yīng)的.maintainers文件例如 basic-old.maintainers 中* Foo Bar foobar會被注入 HTML 的 respec 配置editors字段。版本列表md2html 會收到一份已發(fā)布版本清單path/31.0.0.md\npath/30.0.1.md\npath/30.0.0.md用于生成 respec 配置中的otherLinksOther versions 下拉項(xiàng)。因此在修改規(guī)范 Markdown 時(shí)fixtures目錄既是模板樣本也是回歸測試的基線任何改變標(biāo)題層級、錨點(diǎn)轉(zhuǎn)換或表格渲染的行為都會導(dǎo)致測試失敗。四、真實(shí)版本文件的印證結(jié)構(gòu)與 appendix 體系將 fixture 的骨架與真實(shí)規(guī)范對照可以看到約定在實(shí)際文檔中的規(guī)模版本頭versions/3.0.4.md在標(biāo)題下直接書寫## Version 3.0.4與 BCP 14 關(guān)鍵詞說明MUST / SHOULD / MAY 等隨后是## Introduction、## Definitions等章節(jié)3.0.4.md。Definitions 體系basic-new.md演示了## Definitions下掛### Foo定義條目真實(shí)文檔中### OpenAPI Description、### OpenAPI Document、### Schema均按此模式組織3.0.4.mdmd2html 會為其生成dfn定義標(biāo)記。錨點(diǎn)與交叉引用規(guī)范正文大量使用[See Appendix ...](#appendix-...)形式的內(nèi)部鏈接例如 3.1.1.md 中的附錄 E百分號編碼、附錄 DHeader 與 Cookie 序列化等交叉引用這些目標(biāo)錨點(diǎn)依賴 md2html 對a name/span id的穩(wěn)定轉(zhuǎn)換。修訂歷史真實(shí)文檔以## Appendix A: Revision History收尾3.1.1.md與 fixture 的表格結(jié)構(gòu)一一對應(yīng)。五、代碼塊語言與媒體類型從 basic-new.md 看目標(biāo)輸出能力basic-new.md作為新格式樣例展示了 md2html 對代碼塊語言標(biāo)簽的完整支持面這也是規(guī)范正文中嵌入示例的標(biāo)準(zhǔn)做法語言標(biāo)簽說明樣例內(nèi)容json/yaml最常見的規(guī)范示例如{foo: true}/foo: true配置片段text、無語言、unknown普通文本無高亮text/plain等uriURL 示例含查詢串與片段https://foo.com/bar?bazquxfredwaldo#fragmenturitemplateRFC6570 URI 模板https://foo.com/bar{?baz*,qux}multipartmultipart 媒體類型示例含Content-Type、Content-Location與正文--boundary-example分節(jié)eventstreamSSE 事件流event/data/retry/注釋行addString、addNumber、addJSON事件jsonl/ndjson每行一個(gè) JSON 對象事件流對應(yīng)的行式 JSONjsonseqJSON 文本序列0x1E分隔符 JSON 對象帶時(shí)間戳的兩條日志這些代碼塊在輸出 HTML 中被包裝為pre classnohighlightcode并使用 hljs 主題高亮見 basic-new.html 第 32–103 行。此外basic-new.md還展示了 RFC 引用寫法如[[RFC3986]]、[[RFC9110]]md2html 會將其轉(zhuǎn)換為 bibref 引用或帶 Section 鏈接的引用形式而規(guī)范正文中的 BCP 14 / RFC 關(guān)鍵詞引用見 3.0.4.md即屬于此類。六、Markdown 校驗(yàn)與發(fā)布配置層面的支撐除轉(zhuǎn)換外倉庫還有一整套配置約束規(guī)范正文的書寫質(zhì)量Markdown 風(fēng)格規(guī)則根目錄的 spec.markdownlint.yaml 規(guī)定標(biāo)題必須使用 ATX#前綴風(fēng)格MD003、無序列表必須用*MD004、縮進(jìn) 2 空格MD007、行寬上限 800 字符且表格不參與計(jì)數(shù)MD013、標(biāo)題前后需空行MD022、允許重復(fù)標(biāo)題MD024、允許內(nèi)聯(lián) HTMLMD033——最后一條正是錨點(diǎn)a name能合法存在的原因。校驗(yàn)與構(gòu)建命令package.json 提供validate-markdownoai-spec-validate-markdown、format-markdownoai-spec-format-markdown、buildoai-spec-build、testoai-spec-test等腳本規(guī)范改動的合規(guī)性檢查與構(gòu)建發(fā)布被納入統(tǒng)一命令鏈。發(fā)布期轉(zhuǎn)換根目錄 spec.config.json 的release段說明發(fā)布時(shí)會從src/oas.md生成版本文件并對src/schemas/validation/*.yaml、tests/schema/pass、tests/schema/fail等路徑做 schema 版本號重寫schemaVersionRewrite。也就是說Markdown 結(jié)構(gòu)約定只是 OAS 發(fā)布鏈路的一環(huán)與之配套的還有 schema 與示例的版本同步。七、如何本地查看與驗(yàn)證這套管道查看轉(zhuǎn)換產(chǎn)物fixtures下的.html文件是可直接打開的期望輸出tests/md2html/README.md還說明若要以 respec 格式在本地瀏覽器渲染這些 HTML可執(zhí)行mkdir js cp ../../node_modules/respec/builds/respec-w3c.js js/ echo * js/.gitignore然后本地打開即可倉庫是只讀的這一步驟只涉及本地查看。運(yùn)行測試在倉庫根目錄執(zhí)行yarn test內(nèi)部調(diào)用oai-spec-testmd2html.test.mjs會遍歷 fixtures 中所有.md文件并與.html基線比對任何與本文所述結(jié)構(gòu)約定的偏差都會在此暴露。學(xué)習(xí)完整模板閱讀tests/md2html/fixtures/basic-new.md新格式與versions/3.1.1.md、versions/3.2.1.md等真實(shí)版本正文可以同時(shí)獲得縮微模板與完整成品兩個(gè)視角是編寫或?qū)彶?OAS 規(guī)范文檔的首選參考資料。結(jié)語tests/md2html/fixtures/basic-old.md雖小卻是理解 OpenAPI-Specification 倉庫文檔即代碼、代碼即規(guī)范理念的最佳切入點(diǎn)標(biāo)題層級決定章節(jié)語義Version頭決定 conformance 章節(jié)手寫 TOC 會被丟棄錨點(diǎn)與修訂歷史表格有固定的轉(zhuǎn)換路徑而這一切都被 md2html.test.mjs 與配套的 HTML 基線牢牢鎖定。對任何參與 OAS 規(guī)范維護(hù)或希望自建Markdown 規(guī)范文檔 → respec HTML管道的團(tuán)隊(duì)這套約定與測試模式都值得直接借鑒。贊分享API設(shè)計(jì)文檔后端【免費(fèi)下載鏈接】OpenAPI-SpecificationThe OpenAPI Specification Repository項(xiàng)目地址https://gitcode.com/gh_mirrors/op/OpenAPI-Specification點(diǎn)擊查看免費(fèi)下載相關(guān)推薦OpenAPI Specification 文檔發(fā)布管線剖析md2html 測試夾具與 Respec 渲染機(jī)制OpenAPI Specification 文檔發(fā)布管線剖析md2html 測試夾具與 Respec 渲染機(jī)制 本文以 tests/md2html/fixtuAPI設(shè)計(jì)文檔后端OpenAPI SpecificationSwagger 2.0規(guī)范全解文檔結(jié)構(gòu)、對象定義與機(jī)器可讀 Schema 驗(yàn)證OpenAPI SpecificationSwagger 2.0規(guī)范全解文檔結(jié)構(gòu)、對象定義與機(jī)器可讀 Schema 驗(yàn)證 本篇技術(shù)指南以本倉庫 versiAPI設(shè)計(jì)文檔后端拯救混亂的API文檔OpenAPI-Specification規(guī)范實(shí)戰(zhàn)指南拯救混亂的API文檔OpenAPI Specification規(guī)范實(shí)戰(zhàn)指南 API文檔混亂不堪團(tuán)隊(duì)協(xié)作效率低下OpenAPI SpecificationAPI設(shè)計(jì)文檔后端上一篇Spyder宏錄制開發(fā)者效率革命的終極指南下一篇Semantic Kernel如何約束AI輸出模板工廠與函數(shù)選擇行為拆解創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考