vitepress-openapi 0.2.16 → 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.
- package/dist/{OAJSONEditor-BfaXXObm.js → OAJSONEditor-6uG2SFZK.js} +6 -6
- package/dist/{OAJSONEditor-fTqoBDiY.cjs → OAJSONEditor-D-Yhb6db.cjs} +4 -4
- package/dist/{angular-html-Dl5L_ndT.js → angular-html-BUsdri4u.js} +2 -2
- package/dist/angular-html-BzD9NQW5.cjs +1 -0
- package/dist/{angular-ts-ByuE09su.cjs → angular-ts-D1fX05LE.cjs} +1 -1
- package/dist/{angular-ts-DATG01QH.js → angular-ts-DLzsnsUB.js} +2 -2
- package/dist/{apl-REpE4EOr.cjs → apl-Bo4qJ495.cjs} +1 -1
- package/dist/{apl-B903Y1iI.js → apl-D9bD1gNv.js} +5 -5
- package/dist/{astro-B6XJ1XzP.js → astro-D8q6Gy7P.js} +5 -5
- package/dist/{astro-wd_9JORh.cjs → astro-DCjm-pbh.cjs} +1 -1
- package/dist/{blade-CJNVUHnO.cjs → blade-B6fombNo.cjs} +1 -1
- package/dist/{blade-DU7K6RH3.js → blade-Sc601tfi.js} +7 -7
- package/dist/{c-BFcbaMUO.js → c-CfqZXQ2T.js} +1 -1
- package/dist/c-Dn__oIvS.cjs +1 -0
- package/dist/{chapel-BDpe9hj3.cjs → chapel-D7VyqyYt.cjs} +1 -1
- package/dist/{chapel-CyR2VtwX.js → chapel-xSzmwfXQ.js} +1 -1
- package/dist/{cobol-CDgLba1H.cjs → cobol-CAKxSKZT.cjs} +1 -1
- package/dist/{cobol-ZUVB5fnm.js → cobol-CHAgZDLS.js} +2 -2
- package/dist/{coffee-D9j_lkLc.js → coffee-CeAuLo4O.js} +1 -1
- package/dist/{coffee-BxVt1U7S.cjs → coffee-JnCJAydr.cjs} +1 -1
- package/dist/{core-DCROFLpl.cjs → core-CNg5cW98.cjs} +3 -3
- package/dist/{core-ZiHa6_mm.js → core-s1UIPu_z.js} +114 -114
- package/dist/cpp-1aC9AELp.cjs +1 -0
- package/dist/{cpp-NN3vBjLe.js → cpp-DAEET6ev.js} +3 -3
- package/dist/{crystal-Cg-JMHNA.cjs → crystal-BfArRaXr.cjs} +1 -1
- package/dist/{crystal-BCSv9BMD.js → crystal-C1qz7UnE.js} +6 -6
- package/dist/css-BVuZPxTF.cjs +1 -0
- package/dist/{css-BDew7Z2b.js → css-BZAFXxqD.js} +1 -1
- package/dist/{dist-Dsa_0AoM.cjs → dist-CpZb0vTN.cjs} +5 -5
- package/dist/{dist-CN9hkg4t.js → dist-DV8PoRsD.js} +1 -1
- package/dist/{edge-DXKIJOV7.js → edge-CWZ5MU2M.js} +3 -3
- package/dist/{edge-CMIfIdja.cjs → edge-JzsrLjb_.cjs} +1 -1
- package/dist/{elixir-BjNct3TS.js → elixir-Crtqxz1W.js} +1 -1
- package/dist/{elixir-BmJsBojU.cjs → elixir-QzvqYFsV.cjs} +1 -1
- package/dist/{elm-CPQSACRc.js → elm-9rlZJ0du.js} +1 -1
- package/dist/{elm-rLsOgMwT.cjs → elm-DTTDc-PO.cjs} +1 -1
- package/dist/{engine-javascript-CtAw-nzg.js → engine-javascript-CoT6aZfI.js} +2 -2
- package/dist/{engine-javascript-B9hqc1Sn.cjs → engine-javascript-DWPOYZRs.cjs} +2 -2
- package/dist/{erb-CQUldNHj.js → erb-C6UwauYe.js} +2 -2
- package/dist/{erb-CiTsuMX9.cjs → erb-DPWXQYaP.cjs} +1 -1
- package/dist/generate-BAgVJTNQ.js +103 -0
- package/dist/generate-BVoluROJ.cjs +1 -0
- package/dist/generateMarkdown-BYnrcWs0.js +692 -0
- package/dist/generateMarkdown-DyJdABwj.cjs +31 -0
- package/dist/{git-rebase-CjFDc1kk.cjs → git-rebase-Cwp0uWvv.cjs} +1 -1
- package/dist/{git-rebase-5OapP1hA.js → git-rebase-xIgRvJ_q.js} +1 -1
- package/dist/{glimmer-js-DJj4duzR.js → glimmer-js-CNGdvMhA.js} +4 -4
- package/dist/{glimmer-js-CPs3ZMWA.cjs → glimmer-js-Df_yNNoE.cjs} +1 -1
- package/dist/{glimmer-ts-drtM04VL.js → glimmer-ts-Dq4P7Mkf.js} +4 -4
- package/dist/{glimmer-ts-CuERAYsk.cjs → glimmer-ts-DsAOmOGY.cjs} +1 -1
- package/dist/glsl-CjiF-xkH.cjs +1 -0
- package/dist/{glsl-DPV3oxNS.js → glsl-DZfvb15l.js} +2 -2
- package/dist/{graphql-b3MqwVzn.js → graphql-CZmb-US9.js} +5 -5
- package/dist/graphql-r7AX53Pp.cjs +1 -0
- package/dist/{hack-Dnr29SMc.cjs → hack-Cs2ncrxq.cjs} +1 -1
- package/dist/{hack-BV8Fk8S0.js → hack-DIIRgI4h.js} +2 -2
- package/dist/haml-3bvHwbYf.cjs +1 -0
- package/dist/{haml-DYADyojV.js → haml-aboBnjLl.js} +3 -3
- package/dist/{handlebars-XYDCrTNM.cjs → handlebars-C7PZ80pQ.cjs} +1 -1
- package/dist/{handlebars-D7Wg8zxD.js → handlebars-Z3oHMxHt.js} +4 -4
- package/dist/html-CtaiB3Oi.cjs +1 -0
- package/dist/{html-oFWSlHLM.js → html-Cz0Xqdyq.js} +3 -3
- package/dist/{html-derivative-B_93GY2L.cjs → html-derivative-BYOQo3PG.cjs} +1 -1
- package/dist/{html-derivative-7yg_dBt4.js → html-derivative-BjrHnqif.js} +1 -1
- package/dist/{http-BpWcfGzO.cjs → http-BA9nOlAq.cjs} +1 -1
- package/dist/{http-C-Hd6Lz4.js → http-ieHS9PeS.js} +4 -4
- package/dist/{hurl-D53hSFo7.cjs → hurl-DFGEnvSS.cjs} +1 -1
- package/dist/{hurl-DjXOdham.js → hurl-Dg9NkXrC.js} +2 -2
- package/dist/{java-CcAzK28d.js → java-DCXCvNHA.js} +1 -1
- package/dist/java-DTzZZzv7.cjs +1 -0
- package/dist/javascript-DOKgRqe8.cjs +1 -0
- package/dist/{javascript-CFpHKvG0.js → javascript-f9cb-Pl7.js} +1 -1
- package/dist/{jinja-BzmRQBYE.js → jinja-B2DAjJOY.js} +1 -1
- package/dist/{jinja-DhuEKxK7.cjs → jinja-DE8g1bjX.cjs} +1 -1
- package/dist/{jison-CfNmROg3.js → jison-5BvvygJS.js} +1 -1
- package/dist/{jison-DkP6w3Kb.cjs → jison-BCQciWJO.cjs} +1 -1
- package/dist/js-yaml-B-Up3zwX.cjs +28 -0
- package/dist/{js-yaml-xxJ42vHJ.js → js-yaml-o4oD1Gp3.js} +1 -1
- package/dist/json-BcxNDt_H.cjs +1 -0
- package/dist/{json-BUhydBtV.js → json-DZfYi9f2.js} +1 -1
- package/dist/{jsx-BgXsA-DL.js → jsx-D0ksVAAA.js} +1 -1
- package/dist/jsx-DxOBIFYM.cjs +1 -0
- package/dist/{julia-CFY_QNYf.cjs → julia-B3y7weJz.cjs} +1 -1
- package/dist/{julia-QFUzXXyx.js → julia-Dk4vCuW5.js} +4 -4
- package/dist/{just-unRxJYdl.cjs → just-B7ftAo6t.cjs} +1 -1
- package/dist/{just-BQQqo7uc.js → just-BDbjiXnk.js} +5 -5
- package/dist/{latex-61rhD9l1.js → latex-CC_8gzv9.js} +1 -1
- package/dist/{latex-CMXzYJ7A.cjs → latex-QeOQCy8M.cjs} +1 -1
- package/dist/{liquid-Dlc1A5fD.cjs → liquid-BVZIda1i.cjs} +1 -1
- package/dist/{liquid-DJCM2ZDj.js → liquid-CJVpPXmh.js} +4 -4
- package/dist/llms-DWks2vGp.cjs +26 -0
- package/dist/llms-yFQ0insM.js +418 -0
- package/dist/lua-BoAqNcbB.cjs +1 -0
- package/dist/{lua-CQxTc8eB.js → lua-Bwwgpolt.js} +2 -2
- package/dist/{marko-lDIEsg9U.cjs → marko-CX9I4GhY.cjs} +1 -1
- package/dist/{marko-Dd0qsahM.js → marko-z-UpeqN9.js} +3 -3
- package/dist/{mdc-_80um6kj.js → mdc-ANp6h8jQ.js} +2 -2
- package/dist/{mdc-CyWtd_UH.cjs → mdc-BPd7ZDIZ.cjs} +1 -1
- package/dist/{nginx-DDrDrYzT.js → nginx-BUK9HsFk.js} +1 -1
- package/dist/{nginx-Bys-Mt_F.cjs → nginx-CLECRmW5.cjs} +1 -1
- package/dist/{nim-B-WnW_TA.cjs → nim-4G662efB.cjs} +1 -1
- package/dist/{nim-BKM9BEwv.js → nim-pupbS7ww.js} +6 -6
- package/dist/{useOpenapi-Dr3AneGd.js → normalizeExamples-BFR42ENV.js} +4055 -2184
- package/dist/normalizeExamples-DNaOGXm0.cjs +45 -0
- package/dist/{org-DFPWKQMZ.js → org-B8vjAQ9v.js} +26 -26
- package/dist/{org-BQi9zqMo.cjs → org-XYh7PPQk.cjs} +1 -1
- package/dist/{perl-BIiCtWTQ.js → perl-ChiZYWB8.js} +5 -5
- package/dist/{perl-CkLK5ExR.cjs → perl-Qi4toP6W.cjs} +1 -1
- package/dist/{php-CgjckyHQ.cjs → php-93axekrF.cjs} +1 -1
- package/dist/{php-DOw5HPZo.js → php-JTDYSOFN.js} +6 -6
- package/dist/{pug-ZRJG_B3i.cjs → pug-BHWWe-s7.cjs} +1 -1
- package/dist/{pug-BGkLdaFt.js → pug-BR1NlFnA.js} +3 -3
- package/dist/{qml-BHFWpY8E.cjs → qml-71TJR8lk.cjs} +1 -1
- package/dist/{qml-Bpj0emxI.js → qml-BBCxB4Da.js} +1 -1
- package/dist/r-BVapaf2o.cjs +1 -0
- package/dist/{r-beK_-64Q.js → r-u-VAz7bR.js} +1 -1
- package/dist/{razor-Q3MoMGDn.js → razor-Cqi5RzG6.js} +1 -1
- package/dist/{razor-COBqjWAJ.cjs → razor-DMdT60zm.cjs} +1 -1
- package/dist/{regexp-BsdKen3m.js → regexp-9Pkh3Nf7.js} +1 -1
- package/dist/regexp-CwHm4hi_.cjs +1 -0
- package/dist/{rst-B0t1spY-.cjs → rst-BtwmHjj9.cjs} +1 -1
- package/dist/{rst-DpM5_nag.js → rst-CLZRH5oU.js} +6 -6
- package/dist/{ruby-kbh8ViY5.js → ruby-BZUQEFGQ.js} +12 -12
- package/dist/{ruby-CsFQlb64.cjs → ruby-DuGe7Fs0.cjs} +1 -1
- package/dist/{sas-CnYUys8b.cjs → sas-B7hIWqYI.cjs} +1 -1
- package/dist/{sas-BgQhrf78.js → sas-BO2zDPuE.js} +1 -1
- package/dist/scss-BpK0m8eZ.cjs +1 -0
- package/dist/{scss-NPDrxHVt.js → scss-OFCrSwaR.js} +2 -2
- package/dist/{shellscript-DhwNgJpI.js → shellscript-BNTFxSmg.js} +1 -1
- package/dist/shellscript-KJDkFDLp.cjs +1 -0
- package/dist/{shellsession-BzIHueWc.js → shellsession-B5j5FuGA.js} +1 -1
- package/dist/{shellsession-D7Pf_B_j.cjs → shellsession-DWalcvtJ.cjs} +1 -1
- package/dist/{soy-Bacl__9y.cjs → soy-BQn3ItqC.cjs} +1 -1
- package/dist/{soy-xHdJtla5.js → soy-C2Q794LP.js} +1 -1
- package/dist/{sql-AGUE5-dk.js → sql-8JHRpHTE.js} +1 -1
- package/dist/sql-C5y5nUuw.cjs +1 -0
- package/dist/{stata-BpsgLaw1.js → stata-BrNyU7bS.js} +1 -1
- package/dist/{stata-ByZ8yj3l.cjs → stata-DyBO95gA.cjs} +1 -1
- package/dist/{surrealql-Dfwdqk76.cjs → surrealql-CAAIvFqO.cjs} +1 -1
- package/dist/{surrealql-CE6SK0JG.js → surrealql-DgN6gei3.js} +1 -1
- package/dist/{svelte-DRtnTFsc.cjs → svelte-DGjw_UH1.cjs} +1 -1
- package/dist/{svelte-B8Y6hosE.js → svelte-FhQBX-tv.js} +3 -3
- package/dist/{templ-BofvAMnQ.js → templ-BUggPx5p.js} +2 -2
- package/dist/{templ-BIgW0e2S.cjs → templ-Cxuj5rzV.cjs} +1 -1
- package/dist/tex-B3aY5DbH.cjs +1 -0
- package/dist/{tex-CLtxJoaQ.js → tex-BlOdu2Xy.js} +2 -2
- package/dist/{ts-tags-Cv2SdymF.cjs → ts-tags-BymwG1F9.cjs} +1 -1
- package/dist/{ts-tags-DRRvATIb.js → ts-tags-DZBZzNkR.js} +7 -7
- package/dist/tsx-DgA8B92F.cjs +1 -0
- package/dist/{tsx--6NZUZt2.js → tsx-mByJmMSt.js} +1 -1
- package/dist/{twig-BTg98s4P.js → twig--2v8RtVi.js} +5 -5
- package/dist/{twig-C8K9fEv7.cjs → twig-CWwcCfHy.cjs} +1 -1
- package/dist/types/src/cli.d.ts +1 -0
- package/dist/types/src/components/Common/Highlight/OAShiki.vue.d.ts +2 -2
- package/dist/types/src/components/Common/Highlight/OAVueJsonPretty.vue.d.ts +2 -2
- package/dist/types/src/components/Common/OACodeBlock.vue.d.ts +2 -2
- package/dist/types/src/components/Common/OACodeValue.vue.d.ts +2 -2
- package/dist/types/src/components/Common/OAJSONEditor.vue.d.ts +2 -2
- package/dist/types/src/components/Parameter/OAParameterAttribute.vue.d.ts +2 -2
- package/dist/types/src/components/Playground/OAPlaygroundParameterInput.vue.d.ts +2 -2
- package/dist/types/src/components/ui/badge/index.d.ts +1 -1
- package/dist/types/src/components/ui/button/index.d.ts +1 -1
- package/dist/types/src/index.d.ts +18 -3
- package/dist/types/src/lib/codeSamples/buildOperationRequest.d.ts +15 -0
- package/dist/types/src/lib/codeSamples/buildRequest.d.ts +6 -0
- package/dist/types/src/lib/constants.d.ts +3 -0
- package/dist/types/src/lib/markdown/generateMarkdown.d.ts +111 -0
- package/dist/types/src/lib/markdown/llmsSite.d.ts +137 -0
- package/dist/types/src/lib/markdown/markdownUtils.d.ts +35 -0
- package/dist/types/src/lib/markdown/operationToMarkdown.d.ts +66 -0
- package/dist/types/src/lib/parser/getSchemaUi.d.ts +1 -0
- package/dist/types/src/node/cli.d.ts +5 -0
- package/dist/types/src/node/generate.d.ts +38 -0
- package/dist/types/src/node/llms.d.ts +99 -0
- package/dist/types/src/node/llmsPlugin.d.ts +10 -0
- package/dist/typescript-BWfpZQ2O.cjs +1 -0
- package/dist/{typescript-DBKp3fLc.js → typescript-DF15DAwn.js} +1 -1
- package/dist/{typst-wzR7m38K.cjs → typst-BEqsnZtv.cjs} +1 -1
- package/dist/{typst-BMPcWpxF.js → typst-uhRd3eU5.js} +29 -29
- package/dist/useSidebar-B2LH297o.cjs +6 -0
- package/dist/useSidebar-CoebjdWM.js +313 -0
- package/dist/vitepress-openapi.cli.cjs.js +22 -0
- package/dist/vitepress-openapi.cli.es.js +67 -0
- package/dist/vitepress-openapi.client.cjs.js +1 -1
- package/dist/vitepress-openapi.client.es.js +7 -6
- package/dist/vitepress-openapi.node.cjs.js +1 -1
- package/dist/vitepress-openapi.node.es.js +47 -2
- package/dist/vitepress-openapi.vue.cjs.js +1 -1
- package/dist/vitepress-openapi.vue.es.js +4 -3
- package/dist/{vue-DLzq6csB.cjs → vue-BQl-5Fd6.cjs} +1 -1
- package/dist/{vue-DWAybQg2.js → vue-CSJXDMn1.js} +6 -6
- package/dist/{vue-CPzdKbEl.js → vue-DIM9jH1x.js} +2483 -4670
- package/dist/vue-DwsEa2e4.cjs +7 -0
- package/dist/{vue-html-IeY1Py_m.cjs → vue-html-AqZQgz92.cjs} +1 -1
- package/dist/{vue-html-BSam2lRJ.js → vue-html-DYm4V3uo.js} +1 -1
- package/dist/{vue-vine-icUsAH0H.js → vue-vine-BLrCVeql.js} +3 -3
- package/dist/{vue-vine-Db6Q7xvd.cjs → vue-vine-C1QCIUv6.cjs} +1 -1
- package/dist/xml-DbN80t5u.cjs +1 -0
- package/dist/{xml-Cj_af9Z1.js → xml-Df1jLF7H.js} +2 -2
- package/dist/{xsl-DblyyLAc.cjs → xsl-7fKL5NbN.cjs} +1 -1
- package/dist/{xsl-D-tBFomZ.js → xsl-C2LJLnIq.js} +1 -1
- package/dist/{yaml-D4q2Gm3x.js → yaml-DABI1u00.js} +1 -1
- package/dist/yaml-DNB0t8B9.cjs +1 -0
- package/package.json +4 -1
- package/src/cli.ts +6 -0
- package/src/composables/useSidebar.ts +1 -1
- package/src/index.ts +26 -5
- package/src/lib/codeSamples/buildHarRequest.ts +5 -0
- package/src/lib/codeSamples/buildOperationRequest.ts +52 -0
- package/src/lib/codeSamples/buildRequest.ts +49 -28
- package/src/lib/constants.ts +5 -0
- package/src/lib/examples/getSchemaUiJson.ts +1 -1
- package/src/lib/markdown/generateMarkdown.ts +451 -0
- package/src/lib/markdown/llmsSite.ts +475 -0
- package/src/lib/markdown/markdownUtils.ts +104 -0
- package/src/lib/markdown/operationToMarkdown.ts +834 -0
- package/src/lib/parser/generateCodeSamples.ts +6 -31
- package/src/lib/parser/generateMissingOperationIds.ts +1 -1
- package/src/lib/parser/generateMissingSummary.ts +1 -1
- package/src/lib/parser/generateMissingTags.ts +1 -1
- package/src/lib/parser/generateRequestBodyUi.ts +1 -1
- package/src/lib/parser/generateResponseUi.ts +1 -1
- package/src/lib/parser/generateSecurityUi.ts +1 -1
- package/src/lib/parser/getSchemaUi.ts +7 -3
- package/src/lib/sidebar/generateSidebarItemsByPaths.ts +1 -1
- package/src/lib/spec/createOpenApiSpec.ts +1 -1
- package/src/node/cli.ts +107 -0
- package/src/node/generate.ts +207 -0
- package/src/node/llms.ts +431 -0
- package/src/node/llmsPlugin.ts +29 -0
- package/dist/angular-html-Dk2XGZ_t.cjs +0 -1
- package/dist/c-DkEd8-YD.cjs +0 -1
- package/dist/cpp-BPWm4FiD.cjs +0 -1
- package/dist/css-Cca861pZ.cjs +0 -1
- package/dist/glsl-vKFvWHtP.cjs +0 -1
- package/dist/graphql-DG0SCdKc.cjs +0 -1
- package/dist/haml-cdCU_QQV.cjs +0 -1
- package/dist/html-DOohh95v.cjs +0 -1
- package/dist/java-YSQdp8jH.cjs +0 -1
- package/dist/javascript-CcZ4Z9Pe.cjs +0 -1
- package/dist/js-yaml-D7HstSVO.cjs +0 -28
- package/dist/json-BuUbxxHW.cjs +0 -1
- package/dist/jsx-LBqujUwg.cjs +0 -1
- package/dist/lua-De5jN6Ym.cjs +0 -1
- package/dist/r-CP5u50Ge.cjs +0 -1
- package/dist/regexp-Cquj00oh.cjs +0 -1
- package/dist/scss-FW7lpUTk.cjs +0 -1
- package/dist/shellscript-C1Cbf_Wu.cjs +0 -1
- package/dist/sql-BCbZO9Vk.cjs +0 -1
- package/dist/tex-UEva1VjO.cjs +0 -1
- package/dist/tsx-CRyT9Jau.cjs +0 -1
- package/dist/typescript-BbUbA8EZ.cjs +0 -1
- package/dist/useOpenapi-Bt0dpttK.cjs +0 -50
- package/dist/vue-Da82SaTm.cjs +0 -7
- package/dist/xml-An_1AySF.cjs +0 -1
- package/dist/yaml-BZ7EODQj.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
|
+
}
|