vitepress-openapi 0.2.15 → 0.2.17

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (263) hide show
  1. package/dist/{OAJSONEditor-BPdzinnW.js → OAJSONEditor-6uG2SFZK.js} +6 -6
  2. package/dist/{OAJSONEditor-cdYfH8pW.cjs → OAJSONEditor-D-Yhb6db.cjs} +4 -4
  3. package/dist/{angular-html-D5QwJSjx.js → angular-html-BUsdri4u.js} +2 -2
  4. package/dist/angular-html-BzD9NQW5.cjs +1 -0
  5. package/dist/{angular-ts-CXuTnAMH.cjs → angular-ts-D1fX05LE.cjs} +1 -1
  6. package/dist/{angular-ts-B0kZpGGd.js → angular-ts-DLzsnsUB.js} +2 -2
  7. package/dist/{apl-CjAWNKej.cjs → apl-Bo4qJ495.cjs} +1 -1
  8. package/dist/{apl-CO2hi6pu.js → apl-D9bD1gNv.js} +5 -5
  9. package/dist/{astro-C8AbPvmY.js → astro-D8q6Gy7P.js} +5 -5
  10. package/dist/{astro-C6WzLepe.cjs → astro-DCjm-pbh.cjs} +1 -1
  11. package/dist/{blade-bJOeoSe0.cjs → blade-B6fombNo.cjs} +1 -1
  12. package/dist/{blade-B3TXqIqP.js → blade-Sc601tfi.js} +7 -7
  13. package/dist/{c-BTzN4Ylc.js → c-CfqZXQ2T.js} +1 -1
  14. package/dist/c-Dn__oIvS.cjs +1 -0
  15. package/dist/{chapel-D3SOeXgF.cjs → chapel-D7VyqyYt.cjs} +1 -1
  16. package/dist/{chapel-DqUUkRYq.js → chapel-xSzmwfXQ.js} +1 -1
  17. package/dist/{cobol-dlQjEakv.cjs → cobol-CAKxSKZT.cjs} +1 -1
  18. package/dist/{cobol-DFLW8ca0.js → cobol-CHAgZDLS.js} +2 -2
  19. package/dist/{coffee-1KoIHtzW.js → coffee-CeAuLo4O.js} +1 -1
  20. package/dist/{coffee-TUzF5uor.cjs → coffee-JnCJAydr.cjs} +1 -1
  21. package/dist/{core-x4pNOQS7.cjs → core-CNg5cW98.cjs} +3 -3
  22. package/dist/{core-CSILRXKH.js → core-s1UIPu_z.js} +114 -114
  23. package/dist/cpp-1aC9AELp.cjs +1 -0
  24. package/dist/{cpp-yEMsPd-1.js → cpp-DAEET6ev.js} +3 -3
  25. package/dist/{crystal-D_nHX3jS.cjs → crystal-BfArRaXr.cjs} +1 -1
  26. package/dist/{crystal-CENIitzj.js → crystal-C1qz7UnE.js} +6 -6
  27. package/dist/css-BVuZPxTF.cjs +1 -0
  28. package/dist/{css-B-WLUKlS.js → css-BZAFXxqD.js} +1 -1
  29. package/dist/{dist-BxzxjMCz.cjs → dist-CpZb0vTN.cjs} +5 -5
  30. package/dist/{dist-C1v4Xm4x.js → dist-DV8PoRsD.js} +1 -1
  31. package/dist/{edge-BEj_2N8x.js → edge-CWZ5MU2M.js} +3 -3
  32. package/dist/{edge-f2PDRzgK.cjs → edge-JzsrLjb_.cjs} +1 -1
  33. package/dist/{elixir-CQkxmVTM.js → elixir-Crtqxz1W.js} +1 -1
  34. package/dist/{elixir-CIcaqRsY.cjs → elixir-QzvqYFsV.cjs} +1 -1
  35. package/dist/{elm-DzGi_nR3.js → elm-9rlZJ0du.js} +1 -1
  36. package/dist/{elm-7G0I-hE6.cjs → elm-DTTDc-PO.cjs} +1 -1
  37. package/dist/{engine-javascript-DSMQf2z2.js → engine-javascript-CoT6aZfI.js} +2 -2
  38. package/dist/{engine-javascript-DsJlQOsE.cjs → engine-javascript-DWPOYZRs.cjs} +2 -2
  39. package/dist/{erb-COP2UPZ7.js → erb-C6UwauYe.js} +2 -2
  40. package/dist/{erb-B9-cGaTm.cjs → erb-DPWXQYaP.cjs} +1 -1
  41. package/dist/generate-BAgVJTNQ.js +103 -0
  42. package/dist/generate-BVoluROJ.cjs +1 -0
  43. package/dist/generateMarkdown-BYnrcWs0.js +692 -0
  44. package/dist/generateMarkdown-DyJdABwj.cjs +31 -0
  45. package/dist/{git-rebase-Ku61ihN2.cjs → git-rebase-Cwp0uWvv.cjs} +1 -1
  46. package/dist/{git-rebase-DTYLKCWV.js → git-rebase-xIgRvJ_q.js} +1 -1
  47. package/dist/{glimmer-js-D29AEl8t.js → glimmer-js-CNGdvMhA.js} +4 -4
  48. package/dist/{glimmer-js-izmglT1O.cjs → glimmer-js-Df_yNNoE.cjs} +1 -1
  49. package/dist/{glimmer-ts-DYj3qCHB.js → glimmer-ts-Dq4P7Mkf.js} +4 -4
  50. package/dist/{glimmer-ts-DJ1fakxz.cjs → glimmer-ts-DsAOmOGY.cjs} +1 -1
  51. package/dist/glsl-CjiF-xkH.cjs +1 -0
  52. package/dist/{glsl-Bc6nFncG.js → glsl-DZfvb15l.js} +2 -2
  53. package/dist/{graphql-Ds5Ubte9.js → graphql-CZmb-US9.js} +5 -5
  54. package/dist/graphql-r7AX53Pp.cjs +1 -0
  55. package/dist/{hack-DlUSG6ek.cjs → hack-Cs2ncrxq.cjs} +1 -1
  56. package/dist/{hack-B6E-ISVN.js → hack-DIIRgI4h.js} +2 -2
  57. package/dist/haml-3bvHwbYf.cjs +1 -0
  58. package/dist/{haml-DSK5muqV.js → haml-aboBnjLl.js} +3 -3
  59. package/dist/{handlebars-BxmkFTU3.cjs → handlebars-C7PZ80pQ.cjs} +1 -1
  60. package/dist/{handlebars-CGjGomme.js → handlebars-Z3oHMxHt.js} +4 -4
  61. package/dist/html-CtaiB3Oi.cjs +1 -0
  62. package/dist/{html-DvKVaMAh.js → html-Cz0Xqdyq.js} +3 -3
  63. package/dist/{html-derivative-Due6nHaa.cjs → html-derivative-BYOQo3PG.cjs} +1 -1
  64. package/dist/{html-derivative--Yb6fTDM.js → html-derivative-BjrHnqif.js} +1 -1
  65. package/dist/{http-BDb2okFn.cjs → http-BA9nOlAq.cjs} +1 -1
  66. package/dist/{http-Wf5dll9t.js → http-ieHS9PeS.js} +4 -4
  67. package/dist/{hurl-Ds566NU_.cjs → hurl-DFGEnvSS.cjs} +1 -1
  68. package/dist/{hurl-1Afa28rK.js → hurl-Dg9NkXrC.js} +2 -2
  69. package/dist/{java-DMU2lkyP.js → java-DCXCvNHA.js} +1 -1
  70. package/dist/java-DTzZZzv7.cjs +1 -0
  71. package/dist/javascript-DOKgRqe8.cjs +1 -0
  72. package/dist/{javascript-CkOfli2O.js → javascript-f9cb-Pl7.js} +1 -1
  73. package/dist/{jinja-C_EeM5kX.js → jinja-B2DAjJOY.js} +1 -1
  74. package/dist/{jinja-D65--viX.cjs → jinja-DE8g1bjX.cjs} +1 -1
  75. package/dist/{jison-D5yGxh57.js → jison-5BvvygJS.js} +1 -1
  76. package/dist/{jison-CgJDwgW4.cjs → jison-BCQciWJO.cjs} +1 -1
  77. package/dist/js-yaml-B-Up3zwX.cjs +28 -0
  78. package/dist/{js-yaml-CA-Iojzo.js → js-yaml-o4oD1Gp3.js} +1 -1
  79. package/dist/json-BcxNDt_H.cjs +1 -0
  80. package/dist/{json-DnSlp2pP.js → json-DZfYi9f2.js} +1 -1
  81. package/dist/{jsx-DIHyTcyM.js → jsx-D0ksVAAA.js} +1 -1
  82. package/dist/jsx-DxOBIFYM.cjs +1 -0
  83. package/dist/{julia-Upv7yuF3.cjs → julia-B3y7weJz.cjs} +1 -1
  84. package/dist/{julia-pnYWyN4H.js → julia-Dk4vCuW5.js} +4 -4
  85. package/dist/{just-kcvRoQaC.cjs → just-B7ftAo6t.cjs} +1 -1
  86. package/dist/{just-Rux3ihaI.js → just-BDbjiXnk.js} +5 -5
  87. package/dist/{latex-BNmmGRr9.js → latex-CC_8gzv9.js} +1 -1
  88. package/dist/{latex-ssVj4acX.cjs → latex-QeOQCy8M.cjs} +1 -1
  89. package/dist/{liquid-D9-xfAH9.cjs → liquid-BVZIda1i.cjs} +1 -1
  90. package/dist/{liquid-CkFTSuz5.js → liquid-CJVpPXmh.js} +4 -4
  91. package/dist/llms-DWks2vGp.cjs +26 -0
  92. package/dist/llms-yFQ0insM.js +418 -0
  93. package/dist/lua-BoAqNcbB.cjs +1 -0
  94. package/dist/{lua-BPZzb4jg.js → lua-Bwwgpolt.js} +2 -2
  95. package/dist/{marko-CckGih8c.cjs → marko-CX9I4GhY.cjs} +1 -1
  96. package/dist/{marko-U5lgzX4W.js → marko-z-UpeqN9.js} +3 -3
  97. package/dist/{mdc-ftW0jKss.js → mdc-ANp6h8jQ.js} +2 -2
  98. package/dist/{mdc-CIgbmpvb.cjs → mdc-BPd7ZDIZ.cjs} +1 -1
  99. package/dist/{nginx-CO6FbhYm.js → nginx-BUK9HsFk.js} +1 -1
  100. package/dist/{nginx-pp3BriFA.cjs → nginx-CLECRmW5.cjs} +1 -1
  101. package/dist/{nim-xNROytAe.cjs → nim-4G662efB.cjs} +1 -1
  102. package/dist/{nim-CJpN9IuJ.js → nim-pupbS7ww.js} +6 -6
  103. package/dist/{useOpenapi-DVLwqpMR.js → normalizeExamples-BFR42ENV.js} +4058 -2185
  104. package/dist/normalizeExamples-DNaOGXm0.cjs +45 -0
  105. package/dist/{org-BLgfq4oa.js → org-B8vjAQ9v.js} +26 -26
  106. package/dist/{org-BfvkBzjQ.cjs → org-XYh7PPQk.cjs} +1 -1
  107. package/dist/{perl-4iy1AzjP.js → perl-ChiZYWB8.js} +5 -5
  108. package/dist/{perl-gYxlBF7Z.cjs → perl-Qi4toP6W.cjs} +1 -1
  109. package/dist/{php-D7tWq26a.cjs → php-93axekrF.cjs} +1 -1
  110. package/dist/{php-DBpFECnW.js → php-JTDYSOFN.js} +6 -6
  111. package/dist/{pug-CYLX2lIo.cjs → pug-BHWWe-s7.cjs} +1 -1
  112. package/dist/{pug-B3SC-VJn.js → pug-BR1NlFnA.js} +3 -3
  113. package/dist/{qml-CjtYDlYC.cjs → qml-71TJR8lk.cjs} +1 -1
  114. package/dist/{qml-BJryVNLB.js → qml-BBCxB4Da.js} +1 -1
  115. package/dist/r-BVapaf2o.cjs +1 -0
  116. package/dist/{r-CO3AGhxE.js → r-u-VAz7bR.js} +1 -1
  117. package/dist/{razor-fizwqQUn.js → razor-Cqi5RzG6.js} +1 -1
  118. package/dist/{razor-Cjwm6SbM.cjs → razor-DMdT60zm.cjs} +1 -1
  119. package/dist/{regexp-BlBS23LV.js → regexp-9Pkh3Nf7.js} +1 -1
  120. package/dist/regexp-CwHm4hi_.cjs +1 -0
  121. package/dist/{rst-uzixnQEN.cjs → rst-BtwmHjj9.cjs} +1 -1
  122. package/dist/{rst-CQ-BOew2.js → rst-CLZRH5oU.js} +6 -6
  123. package/dist/{ruby-DYscwpKq.js → ruby-BZUQEFGQ.js} +12 -12
  124. package/dist/{ruby-DcF3FpOo.cjs → ruby-DuGe7Fs0.cjs} +1 -1
  125. package/dist/{sas-CQkHM7U4.cjs → sas-B7hIWqYI.cjs} +1 -1
  126. package/dist/{sas-xf7cYJ8D.js → sas-BO2zDPuE.js} +1 -1
  127. package/dist/scss-BpK0m8eZ.cjs +1 -0
  128. package/dist/{scss-D5Ro0FPj.js → scss-OFCrSwaR.js} +2 -2
  129. package/dist/{shellscript-DVhVbKuT.js → shellscript-BNTFxSmg.js} +1 -1
  130. package/dist/shellscript-KJDkFDLp.cjs +1 -0
  131. package/dist/{shellsession-DCV0F4Wc.js → shellsession-B5j5FuGA.js} +1 -1
  132. package/dist/{shellsession-CfBYvvpU.cjs → shellsession-DWalcvtJ.cjs} +1 -1
  133. package/dist/{soy-HCmyBkD1.cjs → soy-BQn3ItqC.cjs} +1 -1
  134. package/dist/{soy-DqvPS_mm.js → soy-C2Q794LP.js} +1 -1
  135. package/dist/{sql-C8Kl76rR.js → sql-8JHRpHTE.js} +1 -1
  136. package/dist/sql-C5y5nUuw.cjs +1 -0
  137. package/dist/{stata-CJiPjcNk.js → stata-BrNyU7bS.js} +1 -1
  138. package/dist/{stata-B1WKRY4L.cjs → stata-DyBO95gA.cjs} +1 -1
  139. package/dist/{surrealql-D34WxIUj.cjs → surrealql-CAAIvFqO.cjs} +1 -1
  140. package/dist/{surrealql-1H6TjudE.js → surrealql-DgN6gei3.js} +1 -1
  141. package/dist/{svelte-BdqWwltV.cjs → svelte-DGjw_UH1.cjs} +1 -1
  142. package/dist/{svelte-CIN2FBHe.js → svelte-FhQBX-tv.js} +3 -3
  143. package/dist/{templ-DfCxDv8S.js → templ-BUggPx5p.js} +2 -2
  144. package/dist/{templ-DRfIS7Yk.cjs → templ-Cxuj5rzV.cjs} +1 -1
  145. package/dist/tex-B3aY5DbH.cjs +1 -0
  146. package/dist/{tex-BTjGzapI.js → tex-BlOdu2Xy.js} +2 -2
  147. package/dist/{ts-tags-T_iDSaWH.cjs → ts-tags-BymwG1F9.cjs} +1 -1
  148. package/dist/{ts-tags-CV7DYDTm.js → ts-tags-DZBZzNkR.js} +7 -7
  149. package/dist/tsx-DgA8B92F.cjs +1 -0
  150. package/dist/{tsx-C9xVNnaW.js → tsx-mByJmMSt.js} +1 -1
  151. package/dist/{twig-C4i_cRPo.js → twig--2v8RtVi.js} +5 -5
  152. package/dist/{twig-D914CUNQ.cjs → twig-CWwcCfHy.cjs} +1 -1
  153. package/dist/types/src/cli.d.ts +1 -0
  154. package/dist/types/src/components/Common/Highlight/OAShiki.vue.d.ts +2 -2
  155. package/dist/types/src/components/Common/Highlight/OAVueJsonPretty.vue.d.ts +2 -2
  156. package/dist/types/src/components/Common/OACodeBlock.vue.d.ts +2 -2
  157. package/dist/types/src/components/Common/OACodeValue.vue.d.ts +2 -2
  158. package/dist/types/src/components/Common/OAJSONEditor.vue.d.ts +2 -2
  159. package/dist/types/src/components/Parameter/OAParameterAttribute.vue.d.ts +2 -2
  160. package/dist/types/src/components/Playground/OAPlaygroundParameterInput.vue.d.ts +2 -2
  161. package/dist/types/src/components/ui/badge/index.d.ts +1 -1
  162. package/dist/types/src/components/ui/button/index.d.ts +1 -1
  163. package/dist/types/src/composables/useTheme.d.ts +7 -0
  164. package/dist/types/src/index.d.ts +18 -3
  165. package/dist/types/src/lib/codeSamples/buildOperationRequest.d.ts +15 -0
  166. package/dist/types/src/lib/codeSamples/buildRequest.d.ts +6 -0
  167. package/dist/types/src/lib/constants.d.ts +3 -0
  168. package/dist/types/src/lib/markdown/generateMarkdown.d.ts +111 -0
  169. package/dist/types/src/lib/markdown/llmsSite.d.ts +137 -0
  170. package/dist/types/src/lib/markdown/markdownUtils.d.ts +35 -0
  171. package/dist/types/src/lib/markdown/operationToMarkdown.d.ts +66 -0
  172. package/dist/types/src/lib/markdown/sanitizeHtml.d.ts +5 -0
  173. package/dist/types/src/lib/parser/getSchemaUi.d.ts +1 -0
  174. package/dist/types/src/node/cli.d.ts +5 -0
  175. package/dist/types/src/node/generate.d.ts +38 -0
  176. package/dist/types/src/node/llms.d.ts +99 -0
  177. package/dist/types/src/node/llmsPlugin.d.ts +10 -0
  178. package/dist/typescript-BWfpZQ2O.cjs +1 -0
  179. package/dist/{typescript-Chl77Ui1.js → typescript-DF15DAwn.js} +1 -1
  180. package/dist/{typst-C6fVPKNq.cjs → typst-BEqsnZtv.cjs} +1 -1
  181. package/dist/{typst-BgQE6TAB.js → typst-uhRd3eU5.js} +29 -29
  182. package/dist/useSidebar-B2LH297o.cjs +6 -0
  183. package/dist/useSidebar-CoebjdWM.js +313 -0
  184. package/dist/vitepress-openapi.cli.cjs.js +22 -0
  185. package/dist/vitepress-openapi.cli.es.js +67 -0
  186. package/dist/vitepress-openapi.client.cjs.js +1 -1
  187. package/dist/vitepress-openapi.client.es.js +7 -6
  188. package/dist/vitepress-openapi.css +1 -1
  189. package/dist/vitepress-openapi.node.cjs.js +1 -1
  190. package/dist/vitepress-openapi.node.es.js +47 -2
  191. package/dist/vitepress-openapi.vue.cjs.js +1 -1
  192. package/dist/vitepress-openapi.vue.es.js +4 -3
  193. package/dist/{vue-CaajMfVy.cjs → vue-BQl-5Fd6.cjs} +1 -1
  194. package/dist/{vue-J95qJkfJ.js → vue-CSJXDMn1.js} +6 -6
  195. package/dist/{vue-DpVGGK22.js → vue-DIM9jH1x.js} +3091 -4626
  196. package/dist/vue-DwsEa2e4.cjs +7 -0
  197. package/dist/{vue-html-CtmhMKZ8.cjs → vue-html-AqZQgz92.cjs} +1 -1
  198. package/dist/{vue-html-BjrCwjva.js → vue-html-DYm4V3uo.js} +1 -1
  199. package/dist/{vue-vine-C4hFAX9j.js → vue-vine-BLrCVeql.js} +3 -3
  200. package/dist/{vue-vine-DHwm8nhC.cjs → vue-vine-C1QCIUv6.cjs} +1 -1
  201. package/dist/xml-DbN80t5u.cjs +1 -0
  202. package/dist/{xml-4tT4oeZd.js → xml-Df1jLF7H.js} +2 -2
  203. package/dist/{xsl-gK25ns76.cjs → xsl-7fKL5NbN.cjs} +1 -1
  204. package/dist/{xsl-ZTs2D31w.js → xsl-C2LJLnIq.js} +1 -1
  205. package/dist/{yaml-Cr99duBz.js → yaml-DABI1u00.js} +1 -1
  206. package/dist/yaml-DNB0t8B9.cjs +1 -0
  207. package/package.json +6 -2
  208. package/src/cli.ts +6 -0
  209. package/src/composables/useMarkdown.ts +8 -2
  210. package/src/composables/useSidebar.ts +1 -1
  211. package/src/composables/useTheme.ts +12 -0
  212. package/src/index.ts +26 -5
  213. package/src/lib/codeSamples/buildHarRequest.ts +5 -0
  214. package/src/lib/codeSamples/buildOperationRequest.ts +52 -0
  215. package/src/lib/codeSamples/buildRequest.ts +49 -28
  216. package/src/lib/constants.ts +5 -0
  217. package/src/lib/examples/getSchemaUiJson.ts +1 -1
  218. package/src/lib/markdown/generateMarkdown.ts +451 -0
  219. package/src/lib/markdown/llmsSite.ts +475 -0
  220. package/src/lib/markdown/markdownUtils.ts +104 -0
  221. package/src/lib/markdown/operationLink.ts +10 -3
  222. package/src/lib/markdown/operationToMarkdown.ts +834 -0
  223. package/src/lib/markdown/sanitizeHtml.ts +92 -0
  224. package/src/lib/parser/generateCodeSamples.ts +6 -31
  225. package/src/lib/parser/generateMissingOperationIds.ts +1 -1
  226. package/src/lib/parser/generateMissingSummary.ts +1 -1
  227. package/src/lib/parser/generateMissingTags.ts +1 -1
  228. package/src/lib/parser/generateRequestBodyUi.ts +1 -1
  229. package/src/lib/parser/generateResponseUi.ts +1 -1
  230. package/src/lib/parser/generateSecurityUi.ts +1 -1
  231. package/src/lib/parser/getSchemaUi.ts +7 -3
  232. package/src/lib/sidebar/generateSidebarItemsByPaths.ts +1 -1
  233. package/src/lib/spec/createOpenApiSpec.ts +1 -1
  234. package/src/node/cli.ts +107 -0
  235. package/src/node/generate.ts +207 -0
  236. package/src/node/llms.ts +431 -0
  237. package/src/node/llmsPlugin.ts +29 -0
  238. package/dist/angular-html-BoKsRe8T.cjs +0 -1
  239. package/dist/c-BCyoZ90X.cjs +0 -1
  240. package/dist/cpp-tnOfy09q.cjs +0 -1
  241. package/dist/css-02TmpFbt.cjs +0 -1
  242. package/dist/glsl-BGTPqLyQ.cjs +0 -1
  243. package/dist/graphql-DdYH_Rp2.cjs +0 -1
  244. package/dist/haml-D-xAsnlc.cjs +0 -1
  245. package/dist/html-BYiFDapk.cjs +0 -1
  246. package/dist/java-DwnayQnb.cjs +0 -1
  247. package/dist/javascript-CSKossUl.cjs +0 -1
  248. package/dist/js-yaml-uHYMr7LM.cjs +0 -28
  249. package/dist/json-DMvxal4O.cjs +0 -1
  250. package/dist/jsx-CJAVXoYP.cjs +0 -1
  251. package/dist/lua-CbILlNRp.cjs +0 -1
  252. package/dist/r-DKRgTYMs.cjs +0 -1
  253. package/dist/regexp-BbrbtHcV.cjs +0 -1
  254. package/dist/scss-B6SEboBH.cjs +0 -1
  255. package/dist/shellscript-UM_LESkp.cjs +0 -1
  256. package/dist/sql-B2O4UoSw.cjs +0 -1
  257. package/dist/tex-W_Dxzamg.cjs +0 -1
  258. package/dist/tsx-B3iFrpuZ.cjs +0 -1
  259. package/dist/typescript-Ai8puZIn.cjs +0 -1
  260. package/dist/useOpenapi-D3rJQzeG.cjs +0 -50
  261. package/dist/vue-Cdo23EVh.cjs +0 -6
  262. package/dist/xml-C1x13bX0.cjs +0 -1
  263. package/dist/yaml-BUexFoMb.cjs +0 -1
@@ -0,0 +1,834 @@
1
+ import type { LanguageConfig } from '../../composables/useTheme'
2
+ import type { OAExampleObject, ParsedContent, ParsedOperation } from '../../types'
3
+ import type { OAProperty } from '../parser/getSchemaUi'
4
+ import type { OpenApiSpecInstance } from '../spec/createOpenApiSpec'
5
+ import { availableLanguages, DEFAULT_BASE_URL } from '../../composables/useTheme'
6
+ import { buildOperationRequest } from '../codeSamples/buildOperationRequest'
7
+ import { generateCodeSample } from '../codeSamples/generateCodeSample'
8
+ import { getPropertyExample } from '../examples/getPropertyExample'
9
+ import { getSchemaExample } from '../examples/getSchemaExample'
10
+ import { normalizeExamples } from '../examples/normalizeExamples'
11
+ import { formatValueForDisplay } from '../format/formatValueForDisplay'
12
+ import { originSymbol } from '../parser/dereferenceWithAnnotations'
13
+ import { getSchemaUi, SchemaUiCache } from '../parser/getSchemaUi'
14
+ import { getSecurityUi } from '../parser/getSecurityUi'
15
+ import { isJson, isXml } from '../utils/contentTypeUtils'
16
+ import { codeBlock, escapeLinkLabel, heading, indentContinuation, inlineCode, table, withAttributes } from './markdownUtils'
17
+
18
+ export interface OperationToMarkdownOptions {
19
+ /**
20
+ * Heading level of the operation title. Sections use the next levels.
21
+ * @default 1
22
+ */
23
+ headingLevel?: number
24
+ /**
25
+ * URL of the machine-readable OpenAPI document, linked at the end of the page.
26
+ */
27
+ openapiUrl?: string
28
+ /**
29
+ * Code samples to include: `false` to disable, or a list of languages
30
+ * (`lang` ids of the built-in languages, e.g. `'curl'`, `'javascript'`, `'php'`, `'python'`,
31
+ * or custom `LanguageConfig` objects).
32
+ * @default ['curl']
33
+ */
34
+ codeSamples?: boolean | Array<string | LanguageConfig>
35
+ /**
36
+ * Base URL used in code samples. Defaults to the first server of the operation.
37
+ */
38
+ baseUrl?: string
39
+ /**
40
+ * Maximum nesting depth when rendering schemas. Deeper levels are listed as `…`,
41
+ * or as a reference to their component schema.
42
+ * @default 4
43
+ */
44
+ schemaDepth?: number
45
+ /**
46
+ * Autogenerated examples longer than this (in characters) are left out.
47
+ * Examples written in the spec are always kept.
48
+ * @default 10000
49
+ */
50
+ maxExampleLength?: number
51
+ /**
52
+ * Operation links in descriptions, as used by the `operationLink` markdown-it plugin
53
+ * (e.g. `[](/operations/getPet)`): empty link texts are filled with the operation
54
+ * summary and hrefs are mapped with `href`. `false` leaves them untouched.
55
+ * @default { prefix: '/operations/' }
56
+ */
57
+ operationLink?: false | OperationLinkOptions
58
+ }
59
+
60
+ export interface OperationLinkOptions {
61
+ /** @default '/operations/' */
62
+ prefix?: string
63
+ /**
64
+ * Maps an operationId to the link href: `undefined` keeps the original href,
65
+ * `null` drops the link and keeps its text.
66
+ */
67
+ href?: (operationId: string) => string | null | undefined
68
+ }
69
+
70
+ const PARAMETER_LOCATIONS = [
71
+ { in: 'path', title: 'Path parameters' },
72
+ { in: 'query', title: 'Query parameters' },
73
+ { in: 'header', title: 'Header parameters' },
74
+ { in: 'cookie', title: 'Cookie parameters' },
75
+ ] as const
76
+
77
+ const DEFAULT_CODE_SAMPLES = ['curl']
78
+ const DEFAULT_SCHEMA_DEPTH = 4
79
+ const DEFAULT_MAX_EXAMPLE_LENGTH = 10_000
80
+ const IGNORED_CONSTRAINTS = new Set(['format', 'default'])
81
+ const DEFAULT_OPERATION_LINK_PREFIX = '/operations/'
82
+ const RE_MARKDOWN_LINK = /\[([^\]]*)\]\(([^)\s]+)\)/g
83
+ // Leading whitespace is not limited to 3 spaces: fences can be nested in list items.
84
+ const RE_FENCE_OPEN = /^\s*(`{3,}|~{3,})/
85
+ const RE_BACKTICK_RUN = /`+/g
86
+ const RE_OPERATION_ID_END = /[/?#]/
87
+
88
+ interface RenderContext {
89
+ level: number
90
+ schemaDepth: number
91
+ maxExampleLength: number
92
+ schemas: SpecSchemas
93
+ /** Component schemas already expanded in this operation: later uses only reference them. */
94
+ expanded: Set<string>
95
+ }
96
+
97
+ interface SpecSchemas {
98
+ cache: SchemaUiCache
99
+ /** Component schema (by origin) -> its name in `components.schemas`. */
100
+ names: Map<object, string>
101
+ }
102
+
103
+ // Per parsed spec: schemas are converted once, and component names are found by origin.
104
+ const specSchemas = new WeakMap<object, SpecSchemas>()
105
+
106
+ function getSpecSchemas(openapi: OpenApiSpecInstance): SpecSchemas {
107
+ const spec = openapi.getSpec()
108
+ let schemas = specSchemas.get(spec)
109
+ if (!schemas) {
110
+ const names = new Map<object, string>()
111
+ for (const [name, schema] of Object.entries(spec.components?.schemas ?? {})) {
112
+ if (schema && typeof schema === 'object') {
113
+ names.set((schema as any)[originSymbol] ?? schema, name)
114
+ }
115
+ }
116
+ schemas = { cache: new SchemaUiCache(), names }
117
+ specSchemas.set(spec, schemas)
118
+ }
119
+ return schemas
120
+ }
121
+
122
+ /** Name of the component schema a property was built from, if any. */
123
+ function getSchemaName(property: OAProperty, ctx: RenderContext): string | undefined {
124
+ const source = ctx.schemas.cache.sources.get(property) as any
125
+ return source ? ctx.schemas.names.get(source[originSymbol] ?? source) : undefined
126
+ }
127
+
128
+ /**
129
+ * Renders a single operation as plain (GitHub-flavored) Markdown, for static
130
+ * pages, search indexing or LLMs. Expects a parsed spec (e.g. from `useOpenapi`
131
+ * or `generateMarkdownFiles`) so `$ref`s are resolved.
132
+ */
133
+ export async function operationToMarkdown(
134
+ openapi: OpenApiSpecInstance,
135
+ operationId: string,
136
+ options: OperationToMarkdownOptions = {},
137
+ ): Promise<string> {
138
+ const operation: ParsedOperation | null = operationId ? openapi.getOperation(operationId) : null
139
+ if (!operation) {
140
+ return ''
141
+ }
142
+
143
+ const method = openapi.getOperationMethod(operationId) ?? 'get'
144
+ const path = openapi.getOperationPath(operationId) ?? ''
145
+ const ctx: RenderContext = {
146
+ level: options.headingLevel ?? 1,
147
+ schemaDepth: options.schemaDepth ?? DEFAULT_SCHEMA_DEPTH,
148
+ maxExampleLength: options.maxExampleLength ?? DEFAULT_MAX_EXAMPLE_LENGTH,
149
+ schemas: getSpecSchemas(openapi),
150
+ expanded: new Set(),
151
+ }
152
+ const endpoint = `${method.toUpperCase()} ${path}`
153
+
154
+ const blocks: string[] = [
155
+ heading(ctx.level, operation.summary || endpoint),
156
+ inlineCode(endpoint),
157
+ ]
158
+
159
+ if (operation.deprecated) {
160
+ blocks.push('> **Deprecated:** this operation is deprecated and may be removed in a future version.')
161
+ }
162
+
163
+ if (operation.description) {
164
+ blocks.push(String(operation.description).trim())
165
+ }
166
+
167
+ if (operation.externalDocs?.url) {
168
+ blocks.push(`See also: [${escapeLinkLabel(operation.externalDocs.description || operation.externalDocs.url)}](${operation.externalDocs.url})`)
169
+ }
170
+
171
+ blocks.push(
172
+ ...renderServers(openapi.getOperationServers(operationId), ctx),
173
+ ...renderSecurity(openapi, operation, ctx),
174
+ ...renderParameters(getMergedParameters(openapi, operationId), ctx),
175
+ ...renderRequestBody(operation, ctx),
176
+ ...renderResponses(operation, ctx),
177
+ ...await renderCodeSamples(openapi, operationId, operation, options, ctx),
178
+ )
179
+
180
+ if (options.openapiUrl) {
181
+ blocks.push(
182
+ heading(ctx.level + 1, 'OpenAPI'),
183
+ `Machine-readable specification: [${escapeLinkLabel(options.openapiUrl)}](${options.openapiUrl})`,
184
+ )
185
+ }
186
+
187
+ const markdown = blocks.filter(Boolean).join('\n\n')
188
+
189
+ return options.operationLink === false
190
+ ? markdown
191
+ : rewriteOperationLinks(markdown, openapi, options.operationLink ?? {})
192
+ }
193
+
194
+ /**
195
+ * Fills empty operation link texts and maps their hrefs (see `OperationToMarkdownOptions.operationLink`).
196
+ */
197
+ export function rewriteOperationLinks(markdown: string, openapi: OpenApiSpecInstance, options: OperationLinkOptions = {}): string {
198
+ const prefix = options.prefix ?? DEFAULT_OPERATION_LINK_PREFIX
199
+ let fence: { char: string, length: number } | null = null
200
+
201
+ const rewriteLink = (match: string, text: string, href: string) => {
202
+ if (!href.startsWith(prefix)) {
203
+ return match
204
+ }
205
+ let operationId: string
206
+ try {
207
+ operationId = decodeURIComponent(href.slice(prefix.length).split(RE_OPERATION_ID_END)[0])
208
+ }
209
+ catch {
210
+ return match
211
+ }
212
+ const operation = openapi.getOperation(operationId)
213
+ if (!operation) {
214
+ return match
215
+ }
216
+ const target = options.href?.(operationId)
217
+ const label = text || escapeLinkLabel(operation.summary || operationId)
218
+ return target === null ? label : `[${label}](${target ?? href})`
219
+ }
220
+
221
+ return markdown.split('\n').map((line) => {
222
+ if (fence) {
223
+ if (isClosingFence(line, fence)) {
224
+ fence = null
225
+ }
226
+ return line
227
+ }
228
+
229
+ const opening = line.match(RE_FENCE_OPEN)
230
+ // A backtick fence's info string cannot contain backticks (CommonMark).
231
+ if (opening && !(opening[1][0] === '`' && line.slice(opening[0].length).includes('`'))) {
232
+ fence = { char: opening[1][0], length: opening[1].length }
233
+ return line
234
+ }
235
+
236
+ if (!line.includes(prefix)) {
237
+ return line
238
+ }
239
+
240
+ return mapOutsideCodeSpans(line, segment => segment.replace(RE_MARKDOWN_LINK, rewriteLink))
241
+ }).join('\n')
242
+ }
243
+
244
+ /**
245
+ * A closing fence uses the opening character, is at least as long, and has nothing else but whitespace.
246
+ */
247
+ function isClosingFence(line: string, fence: { char: string, length: number }): boolean {
248
+ const trimmed = line.trim()
249
+ return trimmed.length >= fence.length && [...trimmed].every(char => char === fence.char)
250
+ }
251
+
252
+ /**
253
+ * Applies `map` to the parts of a line that are not inline code spans.
254
+ * A span opens with a backtick run and closes with a run of the same length.
255
+ */
256
+ function mapOutsideCodeSpans(line: string, map: (segment: string) => string): string {
257
+ const runs = [...line.matchAll(RE_BACKTICK_RUN)]
258
+ let result = ''
259
+ let cursor = 0
260
+ let index = 0
261
+
262
+ while (index < runs.length) {
263
+ const open = runs[index]
264
+ const closeIndex = runs.findIndex((run, i) => i > index && run[0].length === open[0].length)
265
+ if (closeIndex === -1) {
266
+ // Unmatched run: literal backticks.
267
+ index++
268
+ continue
269
+ }
270
+ const close = runs[closeIndex]
271
+ result += map(line.slice(cursor, open.index)) + line.slice(open.index, close.index! + close[0].length)
272
+ cursor = close.index! + close[0].length
273
+ index = closeIndex + 1
274
+ }
275
+
276
+ return result + map(line.slice(cursor))
277
+ }
278
+
279
+ /**
280
+ * Path item parameters plus operation parameters, keyed by `(name, in)`:
281
+ * an operation parameter overrides the path item one (OpenAPI 3.x).
282
+ */
283
+ function getMergedParameters(openapi: OpenApiSpecInstance, operationId: string): any[] {
284
+ const path = openapi.getOperationPath(operationId)
285
+ const pathParameters = (path ? openapi.getPaths()[path]?.parameters : undefined) ?? []
286
+ const merged = new Map<string, any>()
287
+
288
+ for (const parameter of [...pathParameters, ...openapi.getOperationParameters(operationId)] as any[]) {
289
+ if (!parameter) {
290
+ continue
291
+ }
292
+ // Unresolved `$ref`s have no name/in: keep them apart.
293
+ const key = parameter.name && parameter.in ? `${parameter.in}:${parameter.name}` : `ref:${merged.size}`
294
+ merged.set(key, parameter)
295
+ }
296
+
297
+ return [...merged.values()]
298
+ }
299
+
300
+ function renderServers(servers: any[], ctx: RenderContext): string[] {
301
+ if (!servers?.length) {
302
+ return []
303
+ }
304
+
305
+ const lines = servers.map((server) => {
306
+ const description = server.description ? `: ${server.description}` : ''
307
+ const variables = Object.entries(server.variables ?? {}).map(([name, variable]: [string, any]) => {
308
+ const details = [
309
+ variable.default !== undefined && `default ${inlineCode(variable.default)}`,
310
+ variable.enum?.length && `one of ${variable.enum.map(inlineCode).join(', ')}`,
311
+ variable.description,
312
+ ].filter(Boolean).join('; ')
313
+ return ` - ${inlineCode(`{${name}}`)}${details ? `: ${details}` : ''}`
314
+ })
315
+ return [`- ${inlineCode(server.url)}${description}`, ...variables].join('\n')
316
+ })
317
+
318
+ return [heading(ctx.level + 1, 'Servers'), lines.join('\n')]
319
+ }
320
+
321
+ function renderSecurity(openapi: OpenApiSpecInstance, operation: ParsedOperation, ctx: RenderContext): string[] {
322
+ const spec = openapi.getSpec()
323
+ const requirements: Record<string, string[]>[] = (operation.security ?? spec.security ?? []) as any
324
+ const securityUi = getSecurityUi(requirements as any, (spec.components?.securitySchemes ?? {}) as any)
325
+
326
+ if (!securityUi.length) {
327
+ return []
328
+ }
329
+
330
+ const describe = (index: number, schemes: Record<string, any>, indent: string) => {
331
+ return Object.entries(schemes)
332
+ .map(([name, scheme]) => `${indent}- ${inlineCode(name)}: ${describeSecurityScheme(scheme, requirements[index]?.[name] ?? [], `${indent} `)}`)
333
+ }
334
+
335
+ if (securityUi.length === 1) {
336
+ const schemes = describe(0, securityUi[0].schemes, '')
337
+ return [
338
+ heading(ctx.level + 1, 'Authorization'),
339
+ schemes.length > 1 ? 'All of the following are required:' : '',
340
+ schemes.join('\n'),
341
+ ]
342
+ }
343
+
344
+ const lines = securityUi.flatMap((option, index) => {
345
+ const schemes = describe(index, option.schemes, ' ')
346
+ if (!schemes.length) {
347
+ return [`- Option ${index + 1}: no authentication`]
348
+ }
349
+ return [`- Option ${index + 1}${schemes.length > 1 ? ' (all required)' : ''}:`, ...schemes]
350
+ })
351
+
352
+ return [heading(ctx.level + 1, 'Authorization'), 'Use one of the following options:', lines.join('\n')]
353
+ }
354
+
355
+ /**
356
+ * One-line description of a security scheme (type, location, scopes), with OAuth flows as nested items.
357
+ */
358
+ export function describeSecurityScheme(scheme: any, scopes: string[] = [], indent = ' '): string {
359
+ const parts: string[] = []
360
+ const nested: string[] = []
361
+
362
+ switch (scheme?.type) {
363
+ case 'http': {
364
+ const httpScheme = String(scheme.scheme ?? '').toLowerCase()
365
+ parts.push(`HTTP ${httpScheme || 'authentication'}${scheme.bearerFormat ? ` (${scheme.bearerFormat})` : ''}.`)
366
+ if (httpScheme === 'bearer') {
367
+ parts.push(`Send ${inlineCode('Authorization: Bearer <token>')}.`)
368
+ }
369
+ else if (httpScheme === 'basic') {
370
+ parts.push(`Send ${inlineCode('Authorization: Basic <credentials>')}.`)
371
+ }
372
+ break
373
+ }
374
+ case 'apiKey':
375
+ parts.push(`API key in ${scheme.in ?? 'header'} ${inlineCode(scheme.name ?? '')}.`)
376
+ break
377
+ case 'oauth2':
378
+ parts.push('OAuth 2.0.')
379
+ for (const [flowName, flow] of Object.entries(scheme.flows ?? {}) as [string, any][]) {
380
+ const urls = [
381
+ flow?.authorizationUrl && `authorization URL ${flow.authorizationUrl}`,
382
+ flow?.tokenUrl && `token URL ${flow.tokenUrl}`,
383
+ flow?.refreshUrl && `refresh URL ${flow.refreshUrl}`,
384
+ ].filter(Boolean).join(', ')
385
+ nested.push(`${indent}- Flow ${inlineCode(flowName)}${urls ? `: ${urls}` : ''}`)
386
+ }
387
+ break
388
+ case 'openIdConnect':
389
+ parts.push(`OpenID Connect${scheme.openIdConnectUrl ? ` (${scheme.openIdConnectUrl})` : ''}.`)
390
+ break
391
+ case 'mutualTLS':
392
+ parts.push('Mutual TLS.')
393
+ break
394
+ default:
395
+ parts.push(`${scheme?.type ?? 'Unknown'} scheme.`)
396
+ }
397
+
398
+ if (scopes.length) {
399
+ parts.push(`Required scopes: ${scopes.map(inlineCode).join(', ')}.`)
400
+ }
401
+
402
+ return [indentContinuation(withAttributes(parts.join(' '), [scheme?.description?.trim()]), indent), ...nested].join('\n')
403
+ }
404
+
405
+ function renderParameters(parameters: any[], ctx: RenderContext): string[] {
406
+ const valid = (parameters ?? []).filter(parameter => parameter && parameter.name && parameter.in)
407
+ if (!valid.length) {
408
+ return []
409
+ }
410
+
411
+ const blocks = [heading(ctx.level + 1, 'Parameters')]
412
+
413
+ for (const location of PARAMETER_LOCATIONS) {
414
+ const rows = valid
415
+ .filter(parameter => parameter.in === location.in)
416
+ .map((parameter) => {
417
+ const schema = parameter.schema ?? (Object.values(parameter.content ?? {})[0] as any)?.schema
418
+ const ui = toSchemaUiProperty(schema)
419
+ const description = withAttributes(
420
+ [parameter.deprecated && '**Deprecated.**', parameter.description?.trim()].filter(Boolean).join(' '),
421
+ describeAttributes(ui, getPropertyExample(parameter)),
422
+ )
423
+ return [
424
+ inlineCode(parameter.name),
425
+ ui ? inlineCode(typeLabel(ui)) : '',
426
+ parameter.required ? 'Yes' : 'No',
427
+ description,
428
+ ]
429
+ })
430
+
431
+ if (rows.length) {
432
+ blocks.push(
433
+ heading(ctx.level + 2, location.title),
434
+ table(['Name', 'Type', 'Required', 'Description'], rows),
435
+ )
436
+ }
437
+ }
438
+
439
+ return blocks
440
+ }
441
+
442
+ function renderRequestBody(operation: ParsedOperation, ctx: RenderContext): string[] {
443
+ const requestBody = operation.requestBody
444
+ if (!requestBody) {
445
+ return []
446
+ }
447
+
448
+ const intro = [requestBody.required ? 'Required.' : 'Optional.', requestBody.description?.trim()]
449
+ .filter(Boolean)
450
+ .join(' ')
451
+
452
+ return [
453
+ heading(ctx.level + 1, 'Request body'),
454
+ intro,
455
+ ...renderContent(requestBody.content, ctx),
456
+ ]
457
+ }
458
+
459
+ function renderResponses(operation: ParsedOperation, ctx: RenderContext): string[] {
460
+ const responses = Object.entries(operation.responses ?? {})
461
+ if (!responses.length) {
462
+ return []
463
+ }
464
+
465
+ const blocks = [heading(ctx.level + 1, 'Responses')]
466
+
467
+ for (const [status, response] of responses as [string, any][]) {
468
+ blocks.push(heading(ctx.level + 2, status))
469
+
470
+ if (response?.description) {
471
+ blocks.push(String(response.description).trim())
472
+ }
473
+
474
+ const headers = Object.entries(response?.headers ?? {}) as [string, any][]
475
+ if (headers.length) {
476
+ const rows = headers.map(([name, header]) => {
477
+ const ui = toSchemaUiProperty(header?.schema)
478
+ return [
479
+ inlineCode(name),
480
+ ui ? inlineCode(typeLabel(ui)) : '',
481
+ withAttributes(header?.description, describeAttributes(ui, getPropertyExample(header))),
482
+ ]
483
+ })
484
+ blocks.push('Headers:', table(['Name', 'Type', 'Description'], rows))
485
+ }
486
+
487
+ blocks.push(...renderContent(response?.content, ctx))
488
+ }
489
+
490
+ return blocks
491
+ }
492
+
493
+ function renderContent(content: Record<string, ParsedContent> | undefined, ctx: RenderContext): string[] {
494
+ const blocks: string[] = []
495
+
496
+ for (const [contentType, media] of Object.entries(content ?? {})) {
497
+ blocks.push(`Content type: ${inlineCode(contentType)}`)
498
+
499
+ // Converted again (cached per spec) to know which component schema each property comes from.
500
+ const ui = media?.schema ? getSchemaUi(media.schema, ctx.schemas.cache) : media?.ui
501
+ if (ui) {
502
+ blocks.push(...renderSchema(ui, ctx))
503
+ }
504
+
505
+ for (const example of getMediaExamples(media, contentType, ui, ctx.maxExampleLength)) {
506
+ blocks.push(
507
+ example.title ? `Example (${example.title}):` : 'Example:',
508
+ codeBlock(formatExample(example.value, contentType), exampleLang(example.value, contentType)),
509
+ )
510
+ }
511
+ }
512
+
513
+ return blocks
514
+ }
515
+
516
+ function getMediaExamples(
517
+ media: ParsedContent | undefined,
518
+ contentType: string,
519
+ ui: OAProperty | OAProperty[] | undefined,
520
+ maxExampleLength: number,
521
+ ): Array<{ title?: string, value: unknown }> {
522
+ if (!media) {
523
+ return []
524
+ }
525
+
526
+ if (media.example !== undefined) {
527
+ return [{ value: media.example }]
528
+ }
529
+
530
+ const examples = Object.entries(media.examples ?? {}) as [string, OAExampleObject][]
531
+ const userExamples = examples.filter(([, example]) => !example?.isAutogenerated)
532
+ if (userExamples.length) {
533
+ return (normalizeExamples(Object.fromEntries(userExamples)) ?? [])
534
+ .map(example => ({ title: example.summary || example.name, value: example.value }))
535
+ }
536
+
537
+ const autogenerated = examples.find(([, example]) => example?.isAutogenerated)?.[1]
538
+ ?? (ui ? Object.values(getSchemaExample(contentType, ui, true))[0] : undefined)
539
+
540
+ // Form, multipart and binary bodies are better described by their schema.
541
+ if (!autogenerated || autogenerated.hideOnSchemaTabs || autogenerated.value === undefined || autogenerated.value === '') {
542
+ return []
543
+ }
544
+
545
+ // Huge generated examples (deeply nested schemas) add little over the schema.
546
+ if (formatExample(autogenerated.value, contentType).length > maxExampleLength) {
547
+ return []
548
+ }
549
+
550
+ return [{ value: autogenerated.value }]
551
+ }
552
+
553
+ function formatExample(value: unknown, contentType: string): string {
554
+ if (typeof value === 'string' && !isJson(contentType)) {
555
+ return value
556
+ }
557
+ return formatValueForDisplay(value, { space: 2 })
558
+ }
559
+
560
+ function exampleLang(value: unknown, contentType: string): string {
561
+ if (isXml(contentType)) {
562
+ return 'xml'
563
+ }
564
+ if (isJson(contentType) || typeof value !== 'string') {
565
+ return 'json'
566
+ }
567
+ return 'text'
568
+ }
569
+
570
+ function toSchemaUiProperty(schema: any): OAProperty | undefined {
571
+ if (!schema || typeof schema !== 'object' || Object.keys(schema).length === 0) {
572
+ return undefined
573
+ }
574
+ const ui = getSchemaUi(schema)
575
+ return Array.isArray(ui) ? ui[0] : ui
576
+ }
577
+
578
+ function renderSchema(ui: OAProperty | OAProperty[], ctx: RenderContext): string[] {
579
+ const roots = Array.isArray(ui) ? ui : [ui]
580
+ const blocks: string[] = []
581
+
582
+ for (const root of roots) {
583
+ if (!root) {
584
+ continue
585
+ }
586
+
587
+ if (root.description?.trim()) {
588
+ blocks.push(root.description.trim())
589
+ }
590
+
591
+ const name = getSchemaName(root, ctx)
592
+ if (name && ctx.expanded.has(name)) {
593
+ blocks.push(`Type: ${inlineCode(typeLabel(root))} (see schema ${inlineCode(name)} above).`)
594
+ continue
595
+ }
596
+ if (name) {
597
+ ctx.expanded.add(name)
598
+ }
599
+
600
+ const union = unionLabel(root)
601
+ blocks.push([
602
+ `Type: ${inlineCode(typeLabel(root))}${name ? ` (schema ${inlineCode(name)})` : ''}.`,
603
+ ...describeAttributes(root),
604
+ union && `${union}:`,
605
+ ].filter(Boolean).join(' '))
606
+
607
+ const lines: string[] = []
608
+ renderChildren(root, 0, ctx, lines)
609
+ if (lines.length) {
610
+ blocks.push(lines.join('\n'))
611
+ }
612
+ }
613
+
614
+ return blocks
615
+ }
616
+
617
+ function renderChildren(property: OAProperty, depth: number, ctx: RenderContext, lines: string[]): void {
618
+ if (property.meta?.isCircularReference || !property.properties?.length) {
619
+ return
620
+ }
621
+
622
+ if (depth >= ctx.schemaDepth) {
623
+ lines.push(`${' '.repeat(depth)}- …`)
624
+ return
625
+ }
626
+
627
+ const isUnion = !!unionLabel(property)
628
+ property.properties.forEach((child, index) => {
629
+ const label = isUnion
630
+ ? `Option ${index + 1}${child.title ? ` (${child.title})` : ''}`
631
+ : inlineCode(child.name || `[${index}]`)
632
+ renderProperty(child, label, depth, ctx, lines)
633
+ })
634
+ }
635
+
636
+ function renderProperty(property: OAProperty, label: string, depth: number, ctx: RenderContext, lines: string[]): void {
637
+ const indent = ' '.repeat(depth)
638
+ // A component schema is expanded once per operation; later uses (and uses past the depth limit) reference it.
639
+ const name = getSchemaName(property, ctx)
640
+ const hasChildren = !property.meta?.isCircularReference && !!property.properties?.length
641
+ const reference = !!name && hasChildren && (ctx.expanded.has(name) || depth + 1 >= ctx.schemaDepth)
642
+
643
+ // In code: `<format>` would otherwise be parsed as HTML (e.g. `integer<int64>`).
644
+ const flags = [inlineCode(typeLabel(property))]
645
+ if (name) {
646
+ flags.push(reference ? `see schema ${inlineCode(name)}` : `schema ${inlineCode(name)}`)
647
+ }
648
+ if (property.required) {
649
+ flags.push('required')
650
+ }
651
+ if (property.meta?.isAdditionalProperties) {
652
+ flags.push('additional properties')
653
+ }
654
+
655
+ const union = !reference && unionLabel(property)
656
+ const text = withAttributes(property.description, [...describeAttributes(property), union && `${union}:`])
657
+
658
+ lines.push(`${indent}- ${label} (${flags.join(', ')})${text ? `: ${indentContinuation(text, `${indent} `)}` : ''}`)
659
+ if (reference) {
660
+ return
661
+ }
662
+ if (name) {
663
+ ctx.expanded.add(name)
664
+ }
665
+ renderChildren(property, depth + 1, ctx, lines)
666
+ }
667
+
668
+ function unionLabel(property: OAProperty): string | undefined {
669
+ if (!property.properties?.length) {
670
+ return undefined
671
+ }
672
+ if (property.meta?.isOneOf) {
673
+ return 'One of'
674
+ }
675
+ if (property.meta?.isAnyOf) {
676
+ return 'Any of'
677
+ }
678
+ return undefined
679
+ }
680
+
681
+ /**
682
+ * Compact type label, e.g. `string<uuid>`, `array<object>`, `integer | null`.
683
+ */
684
+ function typeLabel(property: OAProperty): string {
685
+ if (property.meta?.isCircularReference) {
686
+ return 'object'
687
+ }
688
+
689
+ const format = property.constraints?.format as string | undefined
690
+ const types = (property.types ?? []).filter(Boolean)
691
+ const labels = types.map((type) => {
692
+ if (type === 'array') {
693
+ const item = property.items
694
+ ? typeLabel(property.items)
695
+ : property.subtype ?? (property.properties?.length && !property.meta?.hasPrefixItems ? 'object' : undefined)
696
+ return item ? `array<${item}>` : 'array'
697
+ }
698
+ if (format && type !== 'object' && type !== 'null') {
699
+ return `${type}<${format}>`
700
+ }
701
+ return type
702
+ })
703
+
704
+ if (property.nullable && !types.includes('null')) {
705
+ labels.push('null')
706
+ }
707
+
708
+ return labels.join(' | ') || 'any'
709
+ }
710
+
711
+ function describeAttributes(property: OAProperty | undefined, example?: unknown): string[] {
712
+ if (!property) {
713
+ return example != null ? [`Example: ${inlineCode(formatInline(example))}.`] : []
714
+ }
715
+
716
+ const parts: string[] = []
717
+
718
+ if (property.meta?.isConstant) {
719
+ const constant = getPropertyExample(property)
720
+ if (constant != null) {
721
+ parts.push(`Constant: ${inlineCode(formatInline(constant))}.`)
722
+ }
723
+ return parts
724
+ }
725
+
726
+ const enumValues = property.enum ?? property.items?.enum
727
+ if (enumValues?.length) {
728
+ parts.push(`Possible values: ${enumValues.map(value => inlineCode(formatInline(value))).join(', ')}.`)
729
+ }
730
+
731
+ if (property.defaultValue !== undefined) {
732
+ parts.push(`Default: ${inlineCode(formatInline(property.defaultValue))}.`)
733
+ }
734
+
735
+ const constraints = formatConstraints(property.constraints)
736
+ if (constraints) {
737
+ parts.push(`Constraints: ${constraints}.`)
738
+ }
739
+
740
+ // Primitive array items keep their own constraints (e.g. `minLength`), apart from `minItems`.
741
+ const itemConstraints = formatConstraints(property.items?.constraints)
742
+ if (itemConstraints) {
743
+ parts.push(`Items: ${itemConstraints}.`)
744
+ }
745
+
746
+ const resolvedExample = example ?? getPropertyExample(property)
747
+ if (resolvedExample != null) {
748
+ parts.push(`Example: ${inlineCode(formatInline(resolvedExample))}.`)
749
+ }
750
+
751
+ return parts
752
+ }
753
+
754
+ function formatConstraints(constraints: Record<string, unknown> | undefined): string {
755
+ return Object.entries(constraints ?? {})
756
+ .filter(([key]) => !IGNORED_CONSTRAINTS.has(key))
757
+ .map(([key, value]) => `${key}: ${formatInline(value)}`)
758
+ .join(', ')
759
+ }
760
+
761
+ function formatInline(value: unknown): string {
762
+ return typeof value === 'string' ? value : formatValueForDisplay(value, { space: 0 })
763
+ }
764
+
765
+ function resolveLanguages(codeSamples: OperationToMarkdownOptions['codeSamples']): LanguageConfig[] {
766
+ if (codeSamples === false) {
767
+ return []
768
+ }
769
+
770
+ const languages = codeSamples === true || codeSamples === undefined ? DEFAULT_CODE_SAMPLES : codeSamples
771
+ return languages.flatMap((language) => {
772
+ if (typeof language !== 'string') {
773
+ return [language]
774
+ }
775
+ const config = availableLanguages.find(available => available.lang === language)
776
+ if (!config) {
777
+ console.warn(`[vitepress-openapi] Unknown code sample language "${language}". Available: ${availableLanguages.map(available => available.lang).join(', ')}`)
778
+ return []
779
+ }
780
+ return [config]
781
+ })
782
+ }
783
+
784
+ function resolveServerUrl(server: any): string {
785
+ let url = String(server?.url ?? '')
786
+ for (const [name, variable] of Object.entries(server?.variables ?? {}) as [string, any][]) {
787
+ url = url.replaceAll(`{${name}}`, String(variable?.default ?? ''))
788
+ }
789
+
790
+ if (!url) {
791
+ return DEFAULT_BASE_URL
792
+ }
793
+
794
+ // Relative server URLs (e.g. `/api/v1`) are resolved against the default base URL.
795
+ return URL.canParse(url) ? url : new URL(url, DEFAULT_BASE_URL).href
796
+ }
797
+
798
+ async function renderCodeSamples(
799
+ openapi: OpenApiSpecInstance,
800
+ operationId: string,
801
+ operation: ParsedOperation,
802
+ options: OperationToMarkdownOptions,
803
+ ctx: RenderContext,
804
+ ): Promise<string[]> {
805
+ const languages = resolveLanguages(options.codeSamples)
806
+ if (!languages.length) {
807
+ return []
808
+ }
809
+
810
+ const blocks: string[] = []
811
+
812
+ try {
813
+ const baseUrl = (options.baseUrl ?? resolveServerUrl(openapi.getOperationServers(operationId)[0])).replace(/\/+$/, '')
814
+ const request = buildOperationRequest({
815
+ path: openapi.getOperationPath(operationId) ?? '',
816
+ method: openapi.getOperationMethod(operationId) ?? 'get',
817
+ operation,
818
+ parameters: getMergedParameters(openapi, operationId),
819
+ baseUrl,
820
+ })
821
+
822
+ for (const language of languages) {
823
+ const source = await generateCodeSample(language, request)
824
+ if (source) {
825
+ blocks.push(`**${language.label}**`, codeBlock(source, language.highlighter ?? language.lang))
826
+ }
827
+ }
828
+ }
829
+ catch (error) {
830
+ console.warn(`[vitepress-openapi] Could not generate code samples for "${operationId}"`, error)
831
+ }
832
+
833
+ return blocks.length ? [heading(ctx.level + 1, 'Code samples'), ...blocks] : []
834
+ }