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

docs-util: fixes for circular references, PAK in examples, namespaces (#9091)

Browse Source 
- Fix circular references in generated OAS comments by cloning objects
- Add publishable API key in the header of store cURL examples + change the admin authentication header to use bearer tokens.
- Add plugin to generate namespaces from the `@customNamespace` tag in TSDocs, this was available before but was removed.
- Other fixes related to re-using schemas, overwritten descriptions, and smaller fixes
This commit is contained in:
Shahed Nasser
2024-09-16 20:55:05 +03:00
committed by GitHub
parent 05c88268d3
commit cb79a5dbff
10 changed files with 448 additions and 42 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
www/utils/packages/docs-generator/src/classes/examples/oas.ts
View File

@@ -216,11 +216,15 @@ class OasExamplesGenerator {
]
if (isAdminAuthenticated) {
exampleArr.push(`-H 'x-medusa-access-token: {api_token}'`)
exampleArr.push(`-H 'Authorization: Bearer {access_token}'`)
} else if (isStoreAuthenticated) {
exampleArr.push(`-H 'Authorization: Bearer {access_token}'`)
}
if (path.startsWith("/store")) {
exampleArr.push(`-H 'x-publishable-api-key: {your_publishable_api_key}'`)
}
if (requestSchema) {
const requestData = this.getSchemaRequiredData(requestSchema)

38
www/utils/packages/docs-generator/src/classes/helpers/oas-schema.ts
View File

@@ -113,7 +113,9 @@ class OasSchemaHelper {
})
}
this.schemas.set(schema["x-schemaName"], schema)
if (this.canAddSchema(schema)) {
this.schemas.set(schema["x-schemaName"], schema)
}
return {
$ref: this.constructSchemaReference(schema["x-schemaName"]),
@@ -181,6 +183,36 @@ class OasSchemaHelper {
return clonedSchema
}
isSchemaEmpty(schema: OpenApiSchema): boolean {
switch (schema.type) {
case "object":
return (
schema.properties === undefined ||
Object.keys(schema.properties).length === 0
)
case "array":
return (
!this.isRefObject(schema.items) && this.isSchemaEmpty(schema.items)
)
default:
return false
}
}
canAddSchema(schema: OpenApiSchema): boolean {
if (!schema["x-schemaName"]) {
return false
}
const existingSchema = this.schemas.get(schema["x-schemaName"])
if (!existingSchema) {
return true
}
return this.isSchemaEmpty(existingSchema) && !this.isSchemaEmpty(schema)
}
/**
* Retrieve the expected file name of the schema.
*
@@ -212,7 +244,7 @@ class OasSchemaHelper {
// check if it already exists in the schemas map
if (this.schemas.has(schemaName)) {
return {
schema: this.schemas.get(schemaName)!,
schema: JSON.parse(JSON.stringify(this.schemas.get(schemaName)!)),
schemaPrefix: `@schema ${schemaName}`,
}
}
@@ -272,7 +304,7 @@ class OasSchemaHelper {
return name
.replace("DTO", "")
.replace(this.schemaRefPrefix, "")
.replace(/(?<!AdminProduct)Type$/, "")
.replace(/(?<!(AdminProduct|CreateProduct))Type$/, "")
}
/**

2
www/utils/packages/docs-generator/src/classes/helpers/schema-factory.ts
View File

@@ -79,7 +79,7 @@ class SchemaFactory {
schema = Object.assign(schema, {
...additionalData,
// keep the description
description: schema.description || additionalData.description
description: schema.description || additionalData.description,
})
}

115
www/utils/packages/docs-generator/src/classes/kinds/oas.ts
View File

@@ -463,6 +463,7 @@ class OasKindGenerator extends FunctionKindGenerator {
node,
tagName,
methodName,
forUpdate: true,
})
// update query parameters
@@ -511,6 +512,7 @@ class OasKindGenerator extends FunctionKindGenerator {
const newResponseSchema = this.getResponseSchema({
node,
tagName,
forUpdate: true,
})
let updatedResponseSchema: OpenApiSchema | undefined
@@ -968,6 +970,7 @@ class OasKindGenerator extends FunctionKindGenerator {
node,
tagName,
methodName,
forUpdate = false,
}: {
/**
* The node to retrieve its request parameters.
@@ -981,6 +984,10 @@ class OasKindGenerator extends FunctionKindGenerator {
* The tag's name.
*/
tagName?: string
/**
* Whether the request parameters are retrieved for update purposes only.
*/
forUpdate?: boolean
}): {
/**
* The query parameters.
@@ -1041,6 +1048,7 @@ class OasKindGenerator extends FunctionKindGenerator {
title: propertyName,
descriptionOptions,
context: "request",
saveSchema: !forUpdate,
}),
})
)
@@ -1063,6 +1071,7 @@ class OasKindGenerator extends FunctionKindGenerator {
},
zodObjectTypeName: zodObjectTypeName,
context: "request",
saveSchema: !forUpdate,
})
// If function is a GET function, add the type parameter to the
@@ -1135,6 +1144,7 @@ class OasKindGenerator extends FunctionKindGenerator {
getResponseSchema({
node,
tagName,
forUpdate = false,
}: {
/**
* The node to retrieve its response schema.
@@ -1144,6 +1154,10 @@ class OasKindGenerator extends FunctionKindGenerator {
* The tag's name.
*/
tagName?: string
/**
* Whether the response schema is retrieved for update only.
*/
forUpdate?: boolean
}): OpenApiSchema | undefined {
let responseSchema: OpenApiSchema | undefined
@@ -1170,6 +1184,7 @@ class OasKindGenerator extends FunctionKindGenerator {
itemType: responseTypeArguments[0],
}),
context: "response",
saveSchema: !forUpdate,
})
}
}
@@ -1191,6 +1206,7 @@ class OasKindGenerator extends FunctionKindGenerator {
allowedChildren,
disallowedChildren,
zodObjectTypeName,
saveSchema = true,
...rest
}: {
/**
@@ -1229,6 +1245,10 @@ class OasKindGenerator extends FunctionKindGenerator {
* Whether the type is in a request / response
*/
context?: "request" | "response"
/**
* Whether to save object schemas. Useful when only getting schemas to update.
*/
saveSchema?: boolean
}): OpenApiSchema {
if (level > this.MAX_LEVEL) {
return {}
@@ -1354,6 +1374,7 @@ class OasKindGenerator extends FunctionKindGenerator {
parentName: title || descriptionOptions?.parentName,
}
: undefined,
saveSchema,
...rest,
}),
}
@@ -1384,6 +1405,7 @@ class OasKindGenerator extends FunctionKindGenerator {
level,
title,
descriptionOptions,
saveSchema,
...rest,
})
)
@@ -1407,6 +1429,7 @@ class OasKindGenerator extends FunctionKindGenerator {
level,
title,
descriptionOptions,
saveSchema,
...rest,
})
})
@@ -1437,6 +1460,7 @@ class OasKindGenerator extends FunctionKindGenerator {
level,
descriptionOptions,
allowedChildren: pickedProperties,
saveSchema,
...rest,
})
case typeAsString.startsWith("Omit"):
@@ -1458,6 +1482,7 @@ class OasKindGenerator extends FunctionKindGenerator {
level,
descriptionOptions,
disallowedChildren: omitProperties,
saveSchema,
...rest,
})
case typeAsString.startsWith("Partial"):
@@ -1475,6 +1500,7 @@ class OasKindGenerator extends FunctionKindGenerator {
descriptionOptions,
disallowedChildren,
allowedChildren,
saveSchema,
...rest,
})
@@ -1485,13 +1511,29 @@ class OasKindGenerator extends FunctionKindGenerator {
case itemType.isClassOrInterface() ||
itemType.isTypeParameter() ||
(itemType as ts.Type).flags === ts.TypeFlags.Object:
const properties: Record<string, OpenApiSchema> = {}
const properties: Record<
string,
OpenApiSchema | OpenAPIV3.ReferenceObject
> = {}
const requiredProperties: string[] = []
const baseType = itemType.getBaseTypes()?.[0]
const isDeleteResponse =
baseType?.aliasSymbol?.getEscapedName() === "DeleteResponse"
const objSchema: OpenApiSchema = {
type: "object",
description,
"x-schemaName":
itemType.isClassOrInterface() ||
itemType.isTypeParameter() ||
(isZodObject(itemType) && zodObjectTypeName)
? this.oasSchemaHelper.normalizeSchemaName(typeAsString)
: undefined,
// this is changed later
required: undefined,
}
if (level + 1 <= this.MAX_LEVEL) {
itemType.getProperties().forEach((property) => {
if (
@@ -1504,6 +1546,41 @@ class OasKindGenerator extends FunctionKindGenerator {
requiredProperties.push(property.name)
}
const propertyType = this.checker.getTypeOfSymbol(property)
// if property's type is same as parent's property,
// create a reference to the parent
const arrHasParentType =
this.checker.isArrayType(propertyType) &&
this.areTypesEqual(
itemType,
this.checker.getTypeArguments(
propertyType as ts.TypeReference
)[0]
)
const isParentType = this.areTypesEqual(itemType, propertyType)
if (isParentType && objSchema["x-schemaName"]) {
properties[property.name] = {
$ref: this.oasSchemaHelper.constructSchemaReference(
objSchema["x-schemaName"]
),
}
return
} else if (arrHasParentType && objSchema["x-schemaName"]) {
properties[property.name] = {
type: "array",
description,
items: {
$ref: this.oasSchemaHelper.constructSchemaReference(
objSchema["x-schemaName"]
),
},
} as OpenAPIV3.ArraySchemaObject
return
}
properties[property.name] = this.typeToSchema({
itemType: propertyType,
level: level + 1,
@@ -1513,38 +1590,34 @@ class OasKindGenerator extends FunctionKindGenerator {
typeStr: property.name,
parentName: title || descriptionOptions?.parentName,
},
saveSchema,
...rest,
})
if (isDeleteResponse && property.name === "object") {
if (
isDeleteResponse &&
property.name === "object" &&
!this.oasSchemaHelper.isRefObject(properties[property.name])
) {
const schemaProperty = properties[property.name] as OpenApiSchema
// try to retrieve default from `DeleteResponse`'s type argument
const deleteTypeArg = baseType.aliasTypeArguments?.[0]
properties[property.name].default =
schemaProperty.default =
deleteTypeArg && "value" in deleteTypeArg
? (deleteTypeArg.value as string)
: properties[property.name].default
: schemaProperty.default
}
})
}
const objSchema: OpenApiSchema = {
type: "object",
description,
"x-schemaName":
itemType.isClassOrInterface() ||
itemType.isTypeParameter() ||
(isZodObject(itemType) && zodObjectTypeName)
? this.oasSchemaHelper.normalizeSchemaName(typeAsString)
: undefined,
required:
requiredProperties.length > 0 ? requiredProperties : undefined,
}
if (Object.values(properties).length) {
objSchema.properties = properties
}
if (objSchema["x-schemaName"]) {
objSchema.required =
requiredProperties.length > 0 ? requiredProperties : undefined
if (saveSchema && objSchema["x-schemaName"]) {
// add object to schemas to be created
// if necessary
this.oasSchemaHelper.namedSchemaToReference(objSchema)
@@ -1947,8 +2020,6 @@ class OasKindGenerator extends FunctionKindGenerator {
}) || oldSchemaObj.items
}
// update schema
if (
oldSchemaObj!.description !== newSchemaObj?.description &&
oldSchemaObj!.description === SUMMARY_PLACEHOLDER
@@ -2184,6 +2255,10 @@ class OasKindGenerator extends FunctionKindGenerator {
return true
})
}
private areTypesEqual(type1: ts.Type, type2: ts.Type): boolean {
return "id" in type1 && "id" in type2 && type1.id === type2.id
}
}
export default OasKindGenerator