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,451 @@
1
+ import type { OpenAPIDocument } from '../../types'
2
+ import type { OpenApiSpecInstance } from '../spec/createOpenApiSpec'
3
+ import type { OperationToMarkdownOptions } from './operationToMarkdown'
4
+ import slugify from '@sindresorhus/slugify'
5
+ import { parseOpenapi } from '../parser/parseOpenapi'
6
+ import { createOpenApiSpec } from '../spec/createOpenApiSpec'
7
+ import { parseSpec } from '../utils/parseSpec'
8
+ import { markdownToPlainText } from './markdownToPlainText'
9
+ import { escapeLinkLabel, heading, inlineCode, sanitizeFileName, frontmatter as toFrontmatter } from './markdownUtils'
10
+ import { describeSecurityScheme, operationToMarkdown, rewriteOperationLinks } from './operationToMarkdown'
11
+
12
+ export interface GenerateMarkdownFilesOptions extends Omit<OperationToMarkdownOptions, 'headingLevel'> {
13
+ /**
14
+ * One file per operation (`{operationId}.md`) or per tag (`{tag-slug}.md`).
15
+ * @default 'operation'
16
+ */
17
+ groupBy?: 'operation' | 'tag'
18
+ /**
19
+ * Prefix of the links in `llms.txt` (e.g. `/api/` or `https://example.com/api/`).
20
+ * @default '/'
21
+ */
22
+ linkPrefix?: string
23
+ /**
24
+ * Also generate `llms.txt` and `llms-full.txt` (https://llmstxt.org).
25
+ * @default true
26
+ */
27
+ llms?: boolean
28
+ /**
29
+ * Add VitePress frontmatter (title, description, outline) and wrap the content
30
+ * in `::: v-pre` so `{{ }}` in descriptions is not compiled by Vue.
31
+ * @default true
32
+ */
33
+ frontmatter?: boolean
34
+ /**
35
+ * Tag for operations without tags.
36
+ * @default 'Default'
37
+ */
38
+ defaultTag?: string
39
+ }
40
+
41
+ export interface MarkdownFile {
42
+ /** Path relative to the output directory, e.g. `getPet.md`. */
43
+ path: string
44
+ content: string
45
+ }
46
+
47
+ export interface OperationEntry {
48
+ operationId: string
49
+ method: string
50
+ path: string
51
+ summary: string
52
+ description: string
53
+ tags: string[]
54
+ }
55
+
56
+ export interface TagGroup {
57
+ name: string
58
+ description: string
59
+ fileName: string
60
+ operations: OperationEntry[]
61
+ }
62
+
63
+ const RESERVED_FILE_NAMES = ['index', 'llms', 'llms-full']
64
+ const DESCRIPTION_MAX_LENGTH = 160
65
+
66
+ /**
67
+ * Generates plain Markdown files from an OpenAPI document, without touching the
68
+ * file system. Returns the files to write, with paths relative to the output directory.
69
+ */
70
+ export async function generateMarkdownFiles(
71
+ spec: OpenAPIDocument | string | OpenApiSpecInstance,
72
+ options: GenerateMarkdownFilesOptions = {},
73
+ ): Promise<MarkdownFile[]> {
74
+ const {
75
+ groupBy = 'operation',
76
+ linkPrefix = '/',
77
+ llms = true,
78
+ frontmatter = true,
79
+ defaultTag = 'Default',
80
+ ...operationOptions
81
+ } = options
82
+
83
+ const { openapi, operations, groups } = prepareMarkdownSpec(spec, defaultTag)
84
+
85
+ const operationFileNames = new Map(
86
+ createUniqueNames(operations.map(operation => operation.operationId))
87
+ .map((name, index) => [operations[index], name]),
88
+ )
89
+ const tagFileNames = createUniqueNames(groups.map(group => slugify(group.name, { decamelize: false })))
90
+ groups.forEach((group, index) => {
91
+ group.fileName = tagFileNames[index]
92
+ })
93
+
94
+ const fileFor = (operation: OperationEntry, group: TagGroup) => {
95
+ return groupBy === 'tag' ? `${group.fileName}.md` : `${operationFileNames.get(operation)}.md`
96
+ }
97
+
98
+ // Links between operations point to the generated files (relative, same directory).
99
+ const operationLink = operationOptions.operationLink === false
100
+ ? false
101
+ : {
102
+ href: (operationId: string) => {
103
+ const group = groups.find(group => group.operations.some(operation => operation.operationId === operationId))
104
+ const operation = group?.operations.find(operation => operation.operationId === operationId)
105
+ return group && operation ? `./${encodeURI(fileFor(operation, group))}` : undefined
106
+ },
107
+ ...operationOptions.operationLink,
108
+ }
109
+
110
+ // Tag and API descriptions can link to operations too.
111
+ const rewriteLinks = (markdown: string) => {
112
+ return operationLink === false ? markdown : rewriteOperationLinks(markdown, openapi, operationLink)
113
+ }
114
+ groups.forEach((group) => {
115
+ group.description = rewriteLinks(group.description)
116
+ })
117
+
118
+ // Rendered once per heading level: an operation can belong to several tags.
119
+ const rendered = new Map<string, string>()
120
+ const render = async (operation: OperationEntry, headingLevel: number) => {
121
+ const key = `${headingLevel}:${operation.operationId}`
122
+ if (!rendered.has(key)) {
123
+ rendered.set(key, await operationToMarkdown(openapi, operation.operationId, { ...operationOptions, operationLink, headingLevel }))
124
+ }
125
+ return rendered.get(key) ?? ''
126
+ }
127
+
128
+ const files: MarkdownFile[] = []
129
+ const page = (path: string, data: Record<string, unknown>, body: string) => {
130
+ files.push({
131
+ path,
132
+ content: frontmatter
133
+ ? `${toFrontmatter(data)}\n\n::: v-pre\n\n${body}\n\n:::\n`
134
+ : `${body}\n`,
135
+ })
136
+ }
137
+
138
+ if (groupBy === 'tag') {
139
+ for (const group of groups) {
140
+ const sections: string[] = []
141
+ for (const operation of group.operations) {
142
+ sections.push(await render(operation, 2))
143
+ }
144
+ page(`${group.fileName}.md`, {
145
+ title: group.name,
146
+ description: plainText(group.description),
147
+ outline: [2, 3],
148
+ }, renderTagMarkdown(group, sections))
149
+ }
150
+ }
151
+ else {
152
+ for (const operation of operations) {
153
+ page(`${operationFileNames.get(operation)}.md`, {
154
+ title: operation.summary,
155
+ description: plainText(operation.description),
156
+ outline: [2, 3],
157
+ }, await render(operation, 1))
158
+ }
159
+ }
160
+
161
+ const info = openapi.getInfo() ?? {}
162
+
163
+ page('index.md', {
164
+ title: String(info.title || 'API Reference'),
165
+ description: plainText(info.description),
166
+ }, renderIndex(openapi, groups, {
167
+ // Relative links: the files are in the same directory.
168
+ operationUrl: groupBy === 'operation' ? (operation, group) => `./${encodeURI(fileFor(operation, group))}` : undefined,
169
+ tagUrl: groupBy === 'tag' ? group => `./${encodeURI(`${group.fileName}.md`)}` : undefined,
170
+ openapiUrl: operationOptions.openapiUrl,
171
+ rewriteLinks,
172
+ }))
173
+
174
+ if (llms) {
175
+ files.push({
176
+ path: 'llms.txt',
177
+ content: renderLlmsTxt(openapi, groups, {
178
+ operationUrl: (operation, group) => joinLink(linkPrefix, fileFor(operation, group)),
179
+ fullUrl: joinLink(linkPrefix, 'llms-full.txt'),
180
+ openapiUrl: operationOptions.openapiUrl,
181
+ }),
182
+ })
183
+ const sections: string[] = []
184
+ for (const operation of operations) {
185
+ sections.push(await render(operation, 1))
186
+ }
187
+ files.push({ path: 'llms-full.txt', content: renderLlmsFull(openapi, sections) })
188
+ }
189
+
190
+ return files
191
+ }
192
+
193
+ /**
194
+ * Parses the spec (unless it is already an instance) and lists its operations grouped by tag.
195
+ */
196
+ export function prepareMarkdownSpec(spec: OpenAPIDocument | string | OpenApiSpecInstance, defaultTag = 'Default'): {
197
+ openapi: OpenApiSpecInstance
198
+ operations: OperationEntry[]
199
+ groups: TagGroup[]
200
+ } {
201
+ const openapi = toOpenApiSpecInstance(spec, defaultTag)
202
+ const operations = getOperations(openapi)
203
+ return { openapi, operations, groups: getTagGroups(openapi, operations, defaultTag) }
204
+ }
205
+
206
+ function toOpenApiSpecInstance(spec: OpenAPIDocument | string | OpenApiSpecInstance, defaultTag: string): OpenApiSpecInstance {
207
+ if (spec && typeof spec === 'object' && typeof (spec as OpenApiSpecInstance).getOperation === 'function') {
208
+ return spec as OpenApiSpecInstance
209
+ }
210
+
211
+ // Parsing mutates the document (missing operationIds, tags...), so work on a copy.
212
+ const document = typeof spec === 'string' ? spec : structuredClone(spec as OpenAPIDocument)
213
+ const parsed = parseOpenapi().parseSync({ spec: document, defaultTag })
214
+ if (!parsed?.openapi || !parsed.paths) {
215
+ throw new Error('[vitepress-openapi] Invalid OpenAPI document: only OpenAPI 3.x is supported.')
216
+ }
217
+
218
+ return createOpenApiSpec({ spec: parsed, originalSpec: parseSpec(spec as OpenAPIDocument | string) })
219
+ }
220
+
221
+ function getOperations(openapi: OpenApiSpecInstance): OperationEntry[] {
222
+ // Empty operation link texts (`[](/operations/id)`) would vanish from plain-text descriptions.
223
+ const describe = (description: unknown) => rewriteOperationLinks(String(description ?? ''), openapi)
224
+
225
+ return openapi.getPathsByVerbs()
226
+ .filter(entry => entry?.operationId)
227
+ .map(entry => ({
228
+ operationId: String(entry.operationId),
229
+ method: String(entry.verb),
230
+ path: String(entry.path),
231
+ summary: String(entry.summary || `${String(entry.verb).toUpperCase()} ${entry.path}`),
232
+ description: describe(entry.description),
233
+ tags: entry.tags ?? [],
234
+ }))
235
+ }
236
+
237
+ function getTagGroups(openapi: OpenApiSpecInstance, operations: OperationEntry[], defaultTag: string): TagGroup[] {
238
+ const groups: TagGroup[] = openapi.getFilteredTags()
239
+ .filter(tag => tag.name)
240
+ .map(tag => ({
241
+ name: String(tag.name),
242
+ description: tag.description ?? '',
243
+ fileName: '',
244
+ operations: operations.filter(operation => operation.tags.includes(String(tag.name))),
245
+ }))
246
+
247
+ // Only reachable with an unparsed spec instance: parsing assigns `defaultTag`.
248
+ const untagged = operations.filter(operation => operation.tags.length === 0)
249
+ if (untagged.length) {
250
+ const existing = groups.find(group => group.name === defaultTag)
251
+ if (existing) {
252
+ existing.operations.push(...untagged)
253
+ }
254
+ else {
255
+ groups.push({ name: defaultTag, description: '', fileName: '', operations: untagged })
256
+ }
257
+ }
258
+
259
+ return groups.filter(group => group.operations.length > 0)
260
+ }
261
+
262
+ /**
263
+ * Sanitized, unique (case-insensitive) file names that don't clash with index/llms files.
264
+ */
265
+ function createUniqueNames(values: string[]): string[] {
266
+ const used = new Set(RESERVED_FILE_NAMES)
267
+ return values.map((value) => {
268
+ const base = sanitizeFileName(value)
269
+ let name = base
270
+ let suffix = 2
271
+ while (used.has(name.toLowerCase())) {
272
+ name = `${base}-${suffix++}`
273
+ }
274
+ used.add(name.toLowerCase())
275
+ return name
276
+ })
277
+ }
278
+
279
+ function plainText(markdown: string | undefined | null): string {
280
+ return markdownToPlainText(markdown, { maxLength: DESCRIPTION_MAX_LENGTH })
281
+ }
282
+
283
+ function joinLink(prefix: string, file: string): string {
284
+ return `${prefix.endsWith('/') ? prefix : `${prefix}/`}${encodeURI(file)}`
285
+ }
286
+
287
+ function endpoint(operation: OperationEntry): string {
288
+ return `${operation.method.toUpperCase()} ${operation.path}`
289
+ }
290
+
291
+ export interface IndexLinks {
292
+ /** URL of an operation's file, or `undefined` to list it without a link. */
293
+ operationUrl?: (operation: OperationEntry, group: TagGroup) => string | undefined
294
+ /** URL of a tag's file. When set, operations are nested under a link to it. */
295
+ tagUrl?: (group: TagGroup) => string | undefined
296
+ openapiUrl?: string
297
+ /** Applied to the API description (e.g. to rewrite operation links). */
298
+ rewriteLinks?: (markdown: string) => string
299
+ }
300
+
301
+ /**
302
+ * API overview: title, version, description, servers, security schemes and operations grouped by tag.
303
+ */
304
+ export function renderIndex(openapi: OpenApiSpecInstance, groups: TagGroup[], links: IndexLinks = {}): string {
305
+ const info = openapi.getInfo() ?? {}
306
+ const blocks = [heading(1, String(info.title || 'API Reference'))]
307
+
308
+ if (info.version) {
309
+ blocks.push(`Version: ${inlineCode(info.version)}`)
310
+ }
311
+
312
+ if (info.description) {
313
+ const description = String(info.description).trim()
314
+ blocks.push(links.rewriteLinks ? links.rewriteLinks(description) : description)
315
+ }
316
+
317
+ if (links.openapiUrl) {
318
+ blocks.push(`OpenAPI specification: [${escapeLinkLabel(links.openapiUrl)}](${links.openapiUrl})`)
319
+ }
320
+
321
+ const servers = openapi.getServers()
322
+ if (servers.length) {
323
+ blocks.push(
324
+ heading(2, 'Servers'),
325
+ servers.map(server => `- ${inlineCode(server.url)}${server.description ? `: ${server.description}` : ''}`).join('\n'),
326
+ )
327
+ }
328
+
329
+ const securitySchemes = Object.entries(openapi.getSpec().components?.securitySchemes ?? {})
330
+ if (securitySchemes.length) {
331
+ blocks.push(
332
+ // Not "Authentication": a tag often has that name.
333
+ heading(2, 'Security schemes'),
334
+ securitySchemes.map(([name, scheme]) => `- ${inlineCode(name)}: ${describeSecurityScheme(scheme)}`).join('\n'),
335
+ )
336
+ }
337
+
338
+ for (const group of groups) {
339
+ blocks.push(heading(2, group.name))
340
+ if (group.description) {
341
+ blocks.push(group.description.trim())
342
+ }
343
+
344
+ const tagUrl = links.tagUrl?.(group)
345
+ const indent = tagUrl ? ' ' : ''
346
+ const lines = group.operations.map((operation) => {
347
+ const url = links.operationUrl?.(operation, group)
348
+ const title = url ? `[${escapeLinkLabel(operation.summary)}](${url})` : operation.summary
349
+ return `${indent}- ${title} ${inlineCode(endpoint(operation))}`
350
+ })
351
+ blocks.push((tagUrl ? [`- [${escapeLinkLabel(group.name)}](${tagUrl})`, ...lines] : lines).join('\n'))
352
+ }
353
+
354
+ return blocks.join('\n\n')
355
+ }
356
+
357
+ /**
358
+ * A tag page: tag name, description and its rendered operations (one heading level down).
359
+ */
360
+ export function renderTagMarkdown(group: TagGroup, operations: string[]): string {
361
+ return [heading(1, group.name), group.description?.trim(), ...operations].filter(Boolean).join('\n\n')
362
+ }
363
+
364
+ function llmsSummary(openapi: OpenApiSpecInstance): string {
365
+ const info = openapi.getInfo() ?? {}
366
+ const description = markdownToPlainText(rewriteOperationLinks(String(info.description ?? ''), openapi), { maxLength: 300 })
367
+ if (description) {
368
+ return description
369
+ }
370
+ return `API reference for ${info.title || 'this API'}${info.version ? ` (version ${info.version})` : ''}.`
371
+ }
372
+
373
+ export interface LlmsTxtLinks {
374
+ /** URL of an operation's Markdown file. */
375
+ operationUrl: (operation: OperationEntry, group: TagGroup) => string
376
+ /** URL of `llms-full.txt`. */
377
+ fullUrl: string
378
+ openapiUrl?: string
379
+ /** URL of the API overview, listed first. */
380
+ overviewUrl?: string
381
+ /** URL of a tag's file, listed first in its section. */
382
+ tagUrl?: (group: TagGroup) => string | undefined
383
+ /** More `## Section` blocks, before the optional links. */
384
+ extraSections?: string[]
385
+ }
386
+
387
+ /**
388
+ * An `llms.txt` list item for an operation.
389
+ */
390
+ export function llmsOperationLink(operation: OperationEntry, url: string): string {
391
+ const description = markdownToPlainText(operation.description, { maxLength: DESCRIPTION_MAX_LENGTH })
392
+ return `- [${escapeLinkLabel(operation.summary)}](${url}): ${endpoint(operation)}${description ? ` - ${description}` : ''}`
393
+ }
394
+
395
+ /**
396
+ * `llms.txt` (https://llmstxt.org): title, summary and one link per operation, grouped by tag.
397
+ */
398
+ export function renderLlmsTxt(openapi: OpenApiSpecInstance, groups: TagGroup[], links: LlmsTxtLinks): string {
399
+ const info = openapi.getInfo() ?? {}
400
+ const blocks = [
401
+ heading(1, String(info.title || 'API Reference')),
402
+ `> ${llmsSummary(openapi)}`,
403
+ ]
404
+
405
+ const details = [
406
+ links.overviewUrl && `[Overview](${links.overviewUrl}): API description, servers, authentication and all operations`,
407
+ info.version && `Version: ${info.version}`,
408
+ openapi.getServers()[0]?.url && `Base URL: ${openapi.getServers()[0].url}`,
409
+ ].filter(Boolean)
410
+ if (details.length) {
411
+ blocks.push(details.map(detail => `- ${detail}`).join('\n'))
412
+ }
413
+
414
+ for (const group of groups) {
415
+ const tagUrl = links.tagUrl?.(group)
416
+ const lines = group.operations.map(operation => llmsOperationLink(operation, links.operationUrl(operation, group)))
417
+ if (tagUrl) {
418
+ lines.unshift(`- [${escapeLinkLabel(group.name)}](${tagUrl}): all ${group.name} operations in a single file`)
419
+ }
420
+ blocks.push(heading(2, group.name), lines.join('\n'))
421
+ }
422
+
423
+ blocks.push(...(links.extraSections ?? []))
424
+
425
+ blocks.push(
426
+ heading(2, 'Optional'),
427
+ [
428
+ `- [Full documentation](${links.fullUrl}): all operations in a single file`,
429
+ links.openapiUrl && `- [OpenAPI specification](${links.openapiUrl}): machine-readable source of truth`,
430
+ ].filter(Boolean).join('\n'),
431
+ )
432
+
433
+ return `${blocks.join('\n\n')}\n`
434
+ }
435
+
436
+ /**
437
+ * `llms-full.txt`: title and summary, then every rendered operation.
438
+ */
439
+ export function renderLlmsFull(openapi: OpenApiSpecInstance, operations: string[]): string {
440
+ return `${[renderLlmsFullHeader(openapi), ...operations].join(LLMS_FULL_SEPARATOR)}\n`
441
+ }
442
+
443
+ /** Separator between operations in `llms-full.txt`. */
444
+ export const LLMS_FULL_SEPARATOR = '\n\n---\n\n'
445
+
446
+ /**
447
+ * Title and summary at the top of `llms-full.txt`.
448
+ */
449
+ export function renderLlmsFullHeader(openapi: OpenApiSpecInstance): string {
450
+ return `${heading(1, String(openapi.getInfo()?.title || 'API Reference'))}\n\n> ${llmsSummary(openapi)}`
451
+ }