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,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
|
+
}
|