asyavee/medusa-store
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

docs-util: add JS SDK examples to generated OAS (#11935)

Browse Source
This commit is contained in:
Shahed Nasser
2025-03-25 11:11:48 +02:00
committed by GitHub
parent d53af655f0
commit 8a302130b3
8 changed files with 283 additions and 412 deletions
Download Patch File Download Diff File Expand all files Collapse all files
www/utils/packages/docs-generator/src/classes/kinds/oas.ts
+58 -76
View File
@@ -348,45 +348,33 @@ class OasKindGenerator extends FunctionKindGenerator {
tagName,
})
// retrieve code examples
// only generate cURL examples, and for the rest
// check if the --generate-examples option is enabled
oas["x-codeSamples"] = [
{
...OasExamplesGenerator.CURL_CODESAMPLE_DATA,
source: this.oasExamplesGenerator.generateCurlExample({
method: methodName,
path: normalizedOasPath,
isAdminAuthenticated,
isStoreAuthenticated,
requestSchema,
}),
},
]
const curlExample = this.oasExamplesGenerator.generateCurlExample({
method: methodName,
path: normalizedOasPath,
isAdminAuthenticated,
isStoreAuthenticated,
requestSchema,
})
const jsSdkExample = this.oasExamplesGenerator.generateJsSdkExanmple({
method: methodName,
path: normalizedOasPath,
})
if (this.options.generateExamples) {
oas["x-codeSamples"].push(
{
...OasExamplesGenerator.JSCLIENT_CODESAMPLE_DATA,
source: this.oasExamplesGenerator.generateJSClientExample({
oasPath,
httpMethod: methodName,
area: splitOasPath[0] as OasArea,
tag: tagName || "",
isAdminAuthenticated,
isStoreAuthenticated,
parameters: (oas.parameters as OpenAPIV3.ParameterObject[])?.filter(
(parameter) => parameter.in === "path"
),
requestBody: requestSchema,
responseBody: responseSchema,
}),
},
{
...OasExamplesGenerator.MEDUSAREACT_CODESAMPLE_DATA,
source: "EXAMPLE", // TODO figure out if we can generate examples for medusa react
}
)
// retrieve code examples
oas["x-codeSamples"] = []
if (curlExample) {
oas["x-codeSamples"].push({
...OasExamplesGenerator.CURL_CODESAMPLE_DATA,
source: curlExample,
})
}
if (jsSdkExample) {
oas["x-codeSamples"].push({
...OasExamplesGenerator.JSCLIENT_CODESAMPLE_DATA,
source: jsSdkExample,
})
}
// add security details if applicable
@@ -672,44 +660,6 @@ class OasKindGenerator extends FunctionKindGenerator {
}
}
// update examples if the --generate-examples option is enabled
if (this.options.generateExamples) {
const oldJsExampleIndex = oas["x-codeSamples"]
? oas["x-codeSamples"].findIndex(
(example) =>
example.label ==
OasExamplesGenerator.JSCLIENT_CODESAMPLE_DATA.label
)
: -1
if (oldJsExampleIndex === -1) {
// only generate a new example if it doesn't have an example
const newJsExample = this.oasExamplesGenerator.generateJSClientExample({
oasPath,
httpMethod: methodName,
area: splitOasPath[0] as OasArea,
tag: tagName || "",
isAdminAuthenticated,
isStoreAuthenticated,
parameters: (oas.parameters as OpenAPIV3.ParameterObject[])?.filter(
(parameter) => parameter.in === "path"
),
requestBody: updatedRequestSchema?.schema,
responseBody: updatedResponseSchema,
})
oas["x-codeSamples"] = [
...(oas["x-codeSamples"] || []),
{
...OasExamplesGenerator.JSCLIENT_CODESAMPLE_DATA,
source: newJsExample,
},
]
}
// TODO add for Medusa React once we figure out how to generate it
}
// check if cURL example should be updated.
const oldCurlExampleIndex = oas["x-codeSamples"]
? oas["x-codeSamples"].findIndex(
@@ -743,6 +693,38 @@ class OasKindGenerator extends FunctionKindGenerator {
)
}
// generate JS SDK example
const oldJsSdkExampleIndex = oas["x-codeSamples"]
? oas["x-codeSamples"].findIndex(
(example) =>
example.label ===
OasExamplesGenerator.JSCLIENT_CODESAMPLE_DATA.label
)
: -1
const jsSdkExample = this.oasExamplesGenerator.generateJsSdkExanmple({
method: methodName,
path: normalizedOasPath,
})
if (jsSdkExample) {
if (oldJsSdkExampleIndex === -1) {
oas["x-codeSamples"] = [
...(oas["x-codeSamples"] || []),
{
...OasExamplesGenerator.JSCLIENT_CODESAMPLE_DATA,
source: jsSdkExample,
},
]
} else {
oas["x-codeSamples"]![oldJsSdkExampleIndex] = {
...OasExamplesGenerator.JSCLIENT_CODESAMPLE_DATA,
source: jsSdkExample,
}
}
} else if (oldJsSdkExampleIndex !== -1) {
// remove the JS SDK example if it doesn't exist
oas["x-codeSamples"]!.splice(oldJsSdkExampleIndex, 1)
}
// push new tags to the tags property
if (tagName) {
const areaTags = this.tags.get(splitOasPath[0] as OasArea)
www/utils/packages/docs-generator/src/classes/kinds/route-examples.ts
+7 -3
View File
@@ -1,7 +1,6 @@
import ts from "typescript"
import { SyntaxKind } from "typescript"
import DefaultKindGenerator, { GetDocBlockOptions } from "./default.js"
import { API_ROUTE_PARAM_REGEX } from "../../constants.js"
import type { RouteExamples } from "types"
const EXAMPLE_CODEBLOCK_REGEX = /```(ts|typescript)\s*([.\s\S]*?)\s*```/
@@ -105,11 +104,16 @@ class RouteExamplesKindGenerator extends DefaultKindGenerator<ts.MethodDeclarati
node.kind === ts.SyntaxKind.NoSubstitutionTemplateLiteral ||
node.kind === ts.SyntaxKind.TemplateExpression
) {
const str = node
let str = node
.getText()
.replace(/^["'`]|["'`]$/g, "")
.replace(API_ROUTE_PARAM_REGEX, `{$1}`)
.replace(/\$\{(.+?)\}/g, `{$1}`)
.toLowerCase()
// remove possible query params in string
const queryIndex = str.indexOf("?")
if (queryIndex > -1) {
str = str.slice(0, queryIndex)
}
if (
str.startsWith("/store") ||
str.startsWith("/admin") ||