API設(shè)計文檔后端【免費下載鏈接】OpenAPI-SpecificationThe OpenAPI Specification Repository項目地址https://gitcode.com/gh_mirrors/op/OpenAPI-Specification點擊查看免費下載OpenAPI Specification 倉庫OAS不僅定義了 HTTP API 的開放描述標(biāo)準其自身的規(guī)范正文versions/*.md與src/oas.md也有一套嚴格的 Markdown 編寫約定并通過 md2html 工具鏈轉(zhuǎn)換為 W3C 風(fēng)格respec 格式的 HTML 規(guī)范文檔。本文以倉庫測試夾具 basic-old.md 為骨架逐層剖析規(guī)范文檔的標(biāo)題層級、版本頭、conformance 章節(jié)、手寫目錄TOC處理、錨點與修訂歷史表格等結(jié)構(gòu)約定并結(jié)合 md2html.test.mjs 測試、spec.config.json 構(gòu)建配置與真實版本文件說明這套 Markdown 規(guī)范如何被解析、校驗并最終發(fā)布。讀完本文你將理解 OAS 規(guī)范文檔的書寫模板、md2html 轉(zhuǎn)換的行為邊界以及如何在本倉庫中驗證這些約定。一、為什么規(guī)范正文需要一套 Markdown 約定OpenAPI Specification 的源碼是 Markdown 文檔發(fā)布物則是 HTML。從倉庫結(jié)構(gòu)與構(gòu)建腳本可以推斷出如下鏈路規(guī)范主源文件位于src/oas.md由 spec.config.json 中specSrc與release.sourcePath字段指明每個已發(fā)布版本在 versions 目錄下對應(yīng)一份X.Y.Z.md如 3.2.1.md、3.1.1.md、3.0.4.md構(gòu)建時由oai/build-infra包中的 md2html 工具把 Markdown 轉(zhuǎn)成帶 respec 配置的 HTML 規(guī)范頁。正因為轉(zhuǎn)換是程序化的規(guī)范正文的 Markdown 結(jié)構(gòu)就必須穩(wěn)定、可預(yù)測哪些標(biāo)題進入什么層級、哪個段落成為 conformance 章節(jié)、手寫目錄如何被丟棄、錨點如何保留全部由約定與代碼共同保證。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ī)范正文的縮微模板。逐行分析可以看到以下幾個核心結(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)真實文檔中的# OpenAPI Specification標(biāo)題見 3.0.4.md。緊隨其后的#### Version 30.0.1是版本頭。在真實倉庫中它的層級并不統(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 機制可以理解規(guī)范頁的目錄由 respec 腳本根據(jù)文檔標(biāo)題結(jié)構(gòu)自動生成對應(yīng) HTML 中的#toc因此手寫的 TOC 必須刪除以避免重復(fù)與混亂。這一點在 basic-old.html 與 basic-new.html 中均有驗證輸入里的## Table of Contents / Will be removed沒有出現(xiàn)在任何輸出中。3. 錨點anchor的處理a nameparameterAllowEmptyValue/Broken anchor展示了兩種行為該寫法對應(yīng)真實規(guī)范中為關(guān)鍵概念插入的錨點如3.1.1.md中大量[附錄引用](#appendix-...)依賴這類目標(biāo)錨點在舊格式中它以裸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)準的tabletheadtbody結(jié)構(gòu)basic-old.html 第 24–37 行。在真實規(guī)范中這一節(jié)是## Appendix A: Revision History例如 3.1.1.md 的附錄 A 即修訂歷史。從basic-new.md看新格式還會顯式標(biāo)注## Appendix A: Revision History標(biāo)題使章節(jié)進入 respec 的 appendix 語義對應(yīng) basic-new.html 中section classappendix。三、md2html 測試如何鎖定這些行為測試位于 md2html.test.mjs它把fixtures/下每個.md文件作為輸入運行oai/build-infra的 md2html.js并將輸出與同名的.html期望文件做嚴格比對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供測試獨立運行。維護者列表通過--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 下拉項。因此在修改規(guī)范 Markdown 時fixtures目錄既是模板樣本也是回歸測試的基線任何改變標(biāo)題層級、錨點轉(zhuǎn)換或表格渲染的行為都會導(dǎo)致測試失敗。四、真實版本文件的印證結(jié)構(gòu)與 appendix 體系將 fixture 的骨架與真實規(guī)范對照可以看到約定在實際文檔中的規(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定義條目真實文檔中### OpenAPI Description、### OpenAPI Document、### Schema均按此模式組織3.0.4.mdmd2html 會為其生成dfn定義標(biāo)記。錨點與交叉引用規(guī)范正文大量使用[See Appendix ...](#appendix-...)形式的內(nèi)部鏈接例如 3.1.1.md 中的附錄 E百分號編碼、附錄 DHeader 與 Cookie 序列化等交叉引用這些目標(biāo)錨點依賴 md2html 對a name/span id的穩(wěn)定轉(zhuǎn)換。修訂歷史真實文檔以## 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)準做法語言標(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每行一個 JSON 對象事件流對應(yīng)的行式 JSONjsonseqJSON 文本序列0x1E分隔符 JSON 對象帶時間戳的兩條日志這些代碼塊在輸出 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 校驗與發(fā)布配置層面的支撐除轉(zhuǎn)換外倉庫還有一整套配置約束規(guī)范正文的書寫質(zhì)量Markdown 風(fēng)格規(guī)則根目錄的 spec.markdownlint.yaml 規(guī)定標(biāo)題必須使用 ATX#前綴風(fēng)格MD003、無序列表必須用*MD004、縮進 2 空格MD007、行寬上限 800 字符且表格不參與計數(shù)MD013、標(biāo)題前后需空行MD022、允許重復(fù)標(biāo)題MD024、允許內(nèi)聯(lián) HTMLMD033——最后一條正是錨點a name能合法存在的原因。校驗與構(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ā)布時會從src/oas.md生成版本文件并對src/schemas/validation/*.yaml、tests/schema/pass、tests/schema/fail等路徑做 schema 版本號重寫schemaVersionRewrite。也就是說Markdown 結(jié)構(gòu)約定只是 OAS 發(fā)布鏈路的一環(huán)與之配套的還有 schema 與示例的版本同步。七、如何本地查看與驗證這套管道查看轉(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然后本地打開即可倉庫是只讀的這一步驟只涉及本地查看。運行測試在倉庫根目錄執(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等真實版本正文可以同時獲得縮微模板與完整成品兩個視角是編寫或?qū)彶?OAS 規(guī)范文檔的首選參考資料。結(jié)語tests/md2html/fixtures/basic-old.md雖小卻是理解 OpenAPI-Specification 倉庫文檔即代碼、代碼即規(guī)范理念的最佳切入點標(biāo)題層級決定章節(jié)語義Version頭決定 conformance 章節(jié)手寫 TOC 會被丟棄錨點與修訂歷史表格有固定的轉(zhuǎn)換路徑而這一切都被 md2html.test.mjs 與配套的 HTML 基線牢牢鎖定。對任何參與 OAS 規(guī)范維護或希望自建Markdown 規(guī)范文檔 → respec HTML管道的團隊這套約定與測試模式都值得直接借鑒。贊分享API設(shè)計文檔后端【免費下載鏈接】OpenAPI-SpecificationThe OpenAPI Specification Repository項目地址https://gitcode.com/gh_mirrors/op/OpenAPI-Specification點擊查看免費下載相關(guān)推薦OpenAPI Specification 文檔發(fā)布管線剖析md2html 測試夾具與 Respec 渲染機制OpenAPI Specification 文檔發(fā)布管線剖析md2html 測試夾具與 Respec 渲染機制 本文以 tests/md2html/fixtuAPI設(shè)計文檔后端OpenAPI SpecificationSwagger 2.0規(guī)范全解文檔結(jié)構(gòu)、對象定義與機器可讀 Schema 驗證OpenAPI SpecificationSwagger 2.0規(guī)范全解文檔結(jié)構(gòu)、對象定義與機器可讀 Schema 驗證 本篇技術(shù)指南以本倉庫 versiAPI設(shè)計文檔后端拯救混亂的API文檔OpenAPI-Specification規(guī)范實戰(zhàn)指南拯救混亂的API文檔OpenAPI Specification規(guī)范實戰(zhàn)指南 API文檔混亂不堪團隊協(xié)作效率低下OpenAPI SpecificationAPI設(shè)計文檔后端上一篇Spyder宏錄制開發(fā)者效率革命的終極指南下一篇Semantic Kernel如何約束AI輸出模板工廠與函數(shù)選擇行為拆解創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考