@f3liz/rescript-autogen-openapi 0.5.4 → 0.7.0

package/src/core/Templates.res

@@ -0,0 +1,328 @@
+// SPDX-License-Identifier: MPL-2.0
+
+// Templates.res - All Handlebars templates in one place
+
+// === CodegenUtils ===
+
+let fileHeader = `// {{{description}}}
+// Generated by @f3liz/rescript-autogen-openapi
+// DO NOT EDIT - This file is auto-generated
+
+S.enableJson()
+`
+
+let docCommentSingle = `/** {{{content}}} */
+`
+
+let docCommentMulti = `/**
+{{#each lines}}{{{this}}}
+{{/each}}*/
+`
+
+let docComment = `{{#if summary}}// {{{summary}}}
+{{/if}}{{#if description}}// {{{description}}}
+{{/if}}`
+
+// === EndpointGenerator ===
+
+let endpointFunction = `{{{docComment}}}let {{{functionName}}} = async ({{{bodyParam}}}{{{paramSep}}}~fetch: {{{fetchTypeSignature}}}): {{{functionName}}}Response => {
+{{{bodyValueConversion}}}
+  let response = await fetch(
+    ~url="{{{path}}}",
+    ~method_="{{{methodUpper}}}",
+    ~body={{{bodyArg}}},
+  )
+{{{responseHandling}}}
+}`
+
+let moduleWrapped = `{{{header}}}
+
+module {{{moduleName}}} = {
+{{{body}}}
+}`
+
+let moduleUnwrapped = `{{{header}}}
+
+{{{body}}}`
+
+// === ModuleGenerator ===
+
+let indexModule = `{{{header}}}
+
+module {{{moduleName}}} = {
+{{#each tags}}  module {{{modulePascal}}} = {{{modulePascal}}}
+{{/each}}}`
+
+let combinedModule = `{{{header}}}
+
+{{{shared}}}
+
+{{{extension}}}`
+
+// === ThinWrapperGenerator ===
+
+let clientType = `type client = {
+  baseUrl: string,
+  token: option<string>,
+  fetch: {{{fetchTypeSignature}}},
+}`
+
+let connectFunction = `/** Create a client for {{{title}}} */
+let connect = (~baseUrl: string, ~token: option<string>=?, ~fetch: {{{fetchTypeSignature}}}, ()): client => {
+  baseUrl,
+  token,
+  fetch,
+}`
+
+let wrapperFunction = `{{{docComment}}}  {{{signature}}}: promise<{{{generatedModuleName}}}.{{{operationName}}}Response> => 
+    {{{generatedModuleName}}}.{{{operationName}}}({{{callArguments}}}~fetch=client.fetch)`
+
+let wrapperFile = `// Generated thin wrapper
+
+{{{clientTypeCode}}}
+
+{{{connectFunctionCode}}}
+
+{{{modulesCode}}}`
+
+// === TypeScriptDtsGenerator ===
+
+let methodSignature = `{{{docLines}}}
+  {{{functionName}}}({{{params}}}): Promise<{{{responsePascalName}}}Response>;`
+
+let moduleDts = `// TypeScript definitions for {{{moduleName}}}
+// Generated by @f3liz/rescript-autogen-openapi
+// DO NOT EDIT
+
+import { MisskeyClient } from './index';
+import * as ComponentSchemas from './ComponentSchemas';
+
+{{{interfaces}}}
+
+export interface {{{moduleName}}}Module {
+{{{methodSignatures}}}
+}
+
+export const {{{moduleName}}}: {{{moduleName}}}Module;`
+
+let componentSchemasDts = `// TypeScript definitions for ComponentSchemas
+// Generated by @f3liz/rescript-autogen-openapi
+// DO NOT EDIT
+
+{{{content}}}`
+
+let indexDts = `// TypeScript definitions
+// Generated by @f3liz/rescript-autogen-openapi
+// DO NOT EDIT
+
+{{#each modules}}{{{importLine}}}
+{{/each}}
+export class MisskeyClient {
+  constructor(baseUrl: string, token?: string);
+  readonly baseUrl: string;
+  readonly token?: string;
+}
+
+{{#each modules}}{{{exportLine}}}
+{{/each}}`
+
+// === TypeScriptWrapperGenerator ===
+
+let wrapperMjsMethod = `  async {{{functionName}}}(client{{{requestArg}}}) {
+    return {{{moduleName}}}.{{{functionName}}}({
+      {{{bodyArg}}}fetch: (url, method, body) => client._fetch(url, method, body)
+    });
+  },`
+
+let wrapperMjsNamespace = `export const {{{moduleName}}} = {
+{{{methods}}}
+};`
+
+let wrapperMjs = `// Generated wrapper
+{{#each tags}}{{{importLine}}}
+{{/each}}
+{{{clientCode}}}
+
+{{#each tags}}{{{namespace}}}
+
+{{/each}}`
+
+let wrapperDtsFunction = `{{{docComment}}}  export function {{{functionName}}}(client: MisskeyClient{{{requestParam}}}): Promise<{{{pascalName}}}Response>;`
+
+let wrapperDtsNamespace = `export namespace {{{moduleName}}} {
+{{{functions}}}
+}`
+
+let wrapperDts = `// Generated TypeScript definitions for wrapper
+{{#each tags}}{{{importBlock}}}
+{{/each}}
+export class MisskeyClient {
+  constructor(baseUrl: string, token?: string);
+  readonly baseUrl: string;
+  readonly token?: string;
+}
+
+{{#each tags}}{{{namespace}}}
+
+{{/each}}`
+
+// === DiffReportGenerator ===
+
+let mergeReport = `# Merge Report: {{{baseName}}} + {{{forkName}}}
+
+## Shared Code
+
+- **Shared Endpoints**: {{{sharedEndpoints}}}
+- **Shared Schemas**: {{{sharedSchemas}}}
+
+## {{{forkName}}} Extensions
+
+- **Extension Endpoints**: {{{extensionEndpoints}}}
+- **Extension Schemas**: {{{extensionSchemas}}}
+
+## Summary
+
+The shared base contains {{{sharedEndpoints}}} endpoints and {{{sharedSchemas}}} schemas.
+
+{{{forkName}}} adds {{{extensionEndpoints}}} endpoints and {{{extensionSchemas}}} schemas.
+
+---
+*Generated on {{{timestamp}}}*`
+
+// === SchemaCodeGenerator ===
+
+let endpointModule = `{{{docComment}}}module {{{moduleName}}} = {
+{{{schemasCode}}}
+
+  let endpoint = "{{{path}}}"
+  let method = #{{{methodStr}}}
+}`
+
+// === DocOverride ===
+
+let overrideMarkdown = `{{{metadataBlock}}}
+
+# {{{title}}}
+
+**Path**: \`{{{path}}}\`  
+**Method**: \`{{{methodUpper}}}\`  
+**Operation**: \`{{{operationName}}}\`
+
+## Default Description
+
+{{{defaultDesc}}}
+
+## Override
+
+Add your custom documentation here. If this code block is empty, the default description will be used.
+
+\`\`\`
+<!-- Empty - no override -->
+\`\`\``
+
+let overrideReadme = `# API Documentation Overrides
+
+This directory contains markdown files that allow you to override the auto-generated documentation.
+
+## Global Information
+
+- **Host**: {{{hostInfo}}}
+- **Version**: {{{versionInfo}}}
+
+## Structure
+
+Each module has its own directory, and each endpoint has its own markdown file:
+
+\`\`\`
+docs/
+├── README.md (this file)
+├── Account/
+│   ├── postBlockingCreate.md
+│   ├── postBlockingDelete.md
+│   └── ...
+├── Notes/
+│   ├── postNotesCreate.md
+│   └── ...
+└── ...
+\`\`\`
+
+## How to Override
+
+1. Find the endpoint you want to document in its module directory
+2. Open the markdown file
+3. Edit the code block under the "## Override" section
+4. Add your custom documentation (supports markdown)
+5. Regenerate the code - your custom documentation will be used instead of the default
+
+## File Format
+
+Each file contains:
+
+### Frontmatter
+- \`endpoint\`: The API endpoint path
+- \`method\`: HTTP method (GET, POST, etc.)
+- \`hash\`: Hash of the endpoint for change detection
+- \`host\`: API host URL
+- \`version\`: API version
+- \`operationId\`: OpenAPI operation ID
+
+### Default Description
+The original description from the OpenAPI spec.
+
+### Override Section
+A code block where you can add your custom documentation. If empty, the default description is used.
+
+## Example
+
+\`\`\`markdown
+---
+endpoint: /blocking/create
+method: POST
+hash: abc123
+host: https://misskey.io
+version: 1.0.0
+---
+
+# blocking/create
+
+**Path**: \`/blocking/create\`
+**Method**: \`POST\`
+
+## Default Description
+
+No description provided.
+
+**Credential required**: *Yes* / **Permission**: *write:blocks*
+
+## Override
+
+\`\`\`
+Create a blocking relationship with another user.
+
+This endpoint allows you to block a user by their user ID. Once blocked:
+- The user will not be able to see your posts
+- You will not see their posts in your timeline
+- They cannot follow you
+
+**Parameters:**
+- \`userId\`: The ID of the user to block
+
+**Example:**
+\`\`\`typescript
+await client.blocking.create({ userId: "user123" })
+\`\`\`
+\`\`\`
+\`\`\`
+
+## Notes
+
+- The hash is used to detect if the endpoint has changed in the OpenAPI spec
+- If the endpoint changes, you may need to update your override
+- Empty override blocks (with just \`<!-- Empty - no override -->\`) are ignored`
+
+// === ComponentSchemaGenerator ===
+
+let componentSchemaModule = `{{{docComment}}}module {{{moduleName}}} = {
+{{{extractedBlock}}}{{{typeKeyword}}} = {{{typeCode}}}
+  let schema = {{{schemaCode}}}
+}`

package/src/generators/ComponentSchemaGenerator.res

@@ -193,10 +193,14 @@ let generate = (~spec, ~outputDir) => {
         ? `S.recursive("${schema.name}", schema => ${schemaCode})`
         : schemaCode
 
-      `${docComment}module ${CodegenUtils.toPascalCase(schema.name)} = {
-${extractedBlock}  ${typeKeyword} = ${typeCode}
-  let schema = ${finalSchemaCode}
-}`
+      Handlebars.render(Templates.componentSchemaModule, {
+        "docComment": docComment,
+        "moduleName": CodegenUtils.toPascalCase(schema.name),
+        "extractedBlock": extractedBlock,
+        "typeKeyword": `  ${typeKeyword}`,
+        "typeCode": typeCode,
+        "schemaCode": finalSchemaCode,
+      })
     })
 
     let fileHeader = CodegenUtils.generateFileHeader(~description="Shared component schemas")

package/src/generators/DiffReportGenerator.res

@@ -76,35 +76,17 @@ let generateCompactSummary = (diff: specDiff) => {
   `Found ${totalChanges->Int.toString} changes: +${addedCount->Int.toString} -${removedCount->Int.toString} ~${modifiedCount->Int.toString} endpoints${breakingText}`
 }
 
-let generateMergeReport = (~stats: SpecMerger.mergeStats, ~baseName, ~forkName) => {
-  let sharedEndpoints = stats.sharedEndpointCount->Int.toString
-  let sharedSchemas = stats.sharedSchemaCount->Int.toString
-  let extensionEndpoints = stats.forkExtensionCount->Int.toString
-  let extensionSchemas = stats.forkSchemaCount->Int.toString
-
-  `
-    |# Merge Report: ${baseName} + ${forkName}
-    |
-    |## Shared Code
-    |
-    |- **Shared Endpoints**: ${sharedEndpoints}
-    |- **Shared Schemas**: ${sharedSchemas}
-    |
-    |## ${forkName} Extensions
-    |
-    |- **Extension Endpoints**: ${extensionEndpoints}
-    |- **Extension Schemas**: ${extensionSchemas}
-    |
-    |## Summary
-    |
-    |The shared base contains ${sharedEndpoints} endpoints and ${sharedSchemas} schemas.
-    |
-    |${forkName} adds ${extensionEndpoints} endpoints and ${extensionSchemas} schemas.
-    |
-    |---
-    |*Generated on ${Date.make()->Date.toISOString}*
-    |`->CodegenUtils.trimMargin
-}
+let generateMergeReport = (~stats: SpecMerger.mergeStats, ~baseName, ~forkName) =>
+  Handlebars.render(Templates.mergeReport, {
+      "baseName": baseName,
+      "forkName": forkName,
+      "sharedEndpoints": stats.sharedEndpointCount->Int.toString,
+      "sharedSchemas": stats.sharedSchemaCount->Int.toString,
+      "extensionEndpoints": stats.forkExtensionCount->Int.toString,
+      "extensionSchemas": stats.forkSchemaCount->Int.toString,
+      "timestamp": Date.make()->Date.toISOString,
+    },
+  )
 
 let generateEndpointsByTagReport = (endpoints: array<endpoint>) => {
   let endpointsByTag = Dict.make()

package/src/generators/EndpointGenerator.res

@@ -53,9 +53,9 @@ let generateEndpointFunction = (endpoint: endpoint, ~overrideDir=?, ~moduleName=
     ->Array.get(0)
     
   let responseHandling = successResponse->Option.mapOr("  response", response =>
-    response.content->Option.mapOr("  let _ = response\n  ()", content =>
+    response.content->Option.mapOr("  let _ = response", content =>
       Dict.toArray(content)->Array.length > 0
-        ? `  let value = response->S.parseOrThrow(${functionName}ResponseSchema)\n  value`
+        ? `  response->S.parseOrThrow(${functionName}ResponseSchema)`
         : "  response"
     )
   )
@@ -85,21 +85,23 @@ let generateEndpointFunction = (endpoint: endpoint, ~overrideDir=?, ~moduleName=
     (),
   )
   
-  let code = `
-    |${docComment->String.trimEnd}
-    |let ${functionName} = (${bodyParam}${paramSep}~fetch: ${CodegenUtils.fetchTypeSignature}): promise<${functionName}Response> => {
-    |${bodyValueConversion}
-    |  fetch(
-    |    ~url="${endpoint.path}",
-    |    ~method_="${endpoint.method->String.toUpperCase}",
-    |    ~body=${hasRequestBody ? "Some(jsonBody)" : "None"},
-    |  )->Promise.then(response => {
-    |${responseHandling}
-    |    ->Promise.resolve
-    |  })
-    |}`
+  let code = Handlebars.render(
+    Templates.endpointFunction,
+    {
+      "docComment": docComment,
+      "functionName": functionName,
+      "bodyParam": bodyParam,
+      "paramSep": paramSep,
+      "fetchTypeSignature": CodegenUtils.fetchTypeSignature,
+      "bodyValueConversion": bodyValueConversion,
+      "path": endpoint.path,
+      "methodUpper": endpoint.method->String.toUpperCase,
+      "bodyArg": hasRequestBody ? "Some(jsonBody)" : "None",
+      "responseHandling": responseHandling,
+    },
+  )
   
-  code->CodegenUtils.trimMargin
+  code
 }
 
 let generateEndpointCode = (endpoint, ~overrideDir=?, ~moduleName=?, ~modulePrefix="") => {
@@ -143,13 +145,14 @@ let generateEndpointCode = (endpoint, ~overrideDir=?, ~moduleName=?, ~modulePref
 let generateEndpointModule = (~endpoint, ~modulePrefix="") => {
   let functionName = CodegenUtils.generateOperationName(endpoint.operationId, endpoint.path, endpoint.method)
   let header = CodegenUtils.generateFileHeader(~description=endpoint.summary->Option.getOr(`API: ${endpoint.path}`))
-  `
-    |${header->String.trimEnd}
-    |
-    |module ${CodegenUtils.toPascalCase(functionName)} = {
-    |${generateEndpointCode(endpoint, ~modulePrefix)->CodegenUtils.indent(2)}
-    |}
-    |`->CodegenUtils.trimMargin
+  Handlebars.render(
+    Templates.moduleWrapped,
+    {
+      "header": header->String.trimEnd,
+      "moduleName": CodegenUtils.toPascalCase(functionName),
+      "body": generateEndpointCode(endpoint, ~modulePrefix)->CodegenUtils.indent(2),
+    },
+  )
 }
 
 let generateEndpointsModule = (~moduleName, ~endpoints, ~description=?, ~overrideDir=?, ~modulePrefix="") => {
@@ -159,13 +162,14 @@ let generateEndpointsModule = (~moduleName, ~endpoints, ~description=?, ~overrid
     ->Array.map(ep => generateEndpointCode(ep, ~overrideDir?, ~moduleName, ~modulePrefix)->CodegenUtils.indent(2))
     ->Array.join("\n\n")
 
-  `
-    |${header->String.trimEnd}
-    |
-    |module ${moduleName} = {
-    |${body}
-    |}
-    |`->CodegenUtils.trimMargin
+  Handlebars.render(
+    Templates.moduleWrapped,
+    {
+      "header": header->String.trimEnd,
+      "moduleName": moduleName,
+      "body": body,
+    },
+  )
 }
 
 let generateEndpointSignature = (endpoint) => {

package/src/generators/ModuleGenerator.res

@@ -63,19 +63,22 @@ let generateTagModuleFile = (
     ->Array.join("\n\n")
 
   if wrapInModule {
-    `
-      |${header->String.trimEnd}
-      |
-      |module ${moduleName} = {
-      |${body->CodegenUtils.indent(2)}
-      |}
-      |`->CodegenUtils.trimMargin
+    Handlebars.render(
+      Templates.moduleWrapped,
+      {
+        "header": header->String.trimEnd,
+        "moduleName": moduleName,
+        "body": body->CodegenUtils.indent(2),
+      },
+    )
   } else {
-    `
-      |${header->String.trimEnd}
-      |
-      |${body}
-      |`->CodegenUtils.trimMargin
+    Handlebars.render(
+      Templates.moduleUnwrapped,
+      {
+        "header": header->String.trimEnd,
+        "body": body,
+      },
+    )
   }
 }
 
@@ -96,22 +99,19 @@ let generateAllTagModules = (
 
 let generateIndexModule = (~tags, ~moduleName="API") => {
   let header = CodegenUtils.generateFileHeader(~description="Main API module index")
-  let modules =
+  let tagData =
     tags
     ->Array.toSorted(String.compare)
-    ->Array.map(tag => {
-      let m = CodegenUtils.toPascalCase(tag)
-      `  module ${m} = ${m}`
-    })
-    ->Array.join("\n")
+    ->Array.map(tag => {"modulePascal": CodegenUtils.toPascalCase(tag)})
 
-  `
-    |${header->String.trimEnd}
-    |
-    |module ${moduleName} = {
-    |${modules}
-    |}
-    |`->CodegenUtils.trimMargin
+  Handlebars.render(
+    Templates.indexModule,
+    {
+      "header": header->String.trimEnd,
+      "moduleName": moduleName,
+      "tags": tagData,
+    },
+  )
 }
 
 let generateFlatModuleCode = (~moduleName, ~endpoints, ~overrideDir=?) => {
@@ -127,13 +127,14 @@ let generateFlatModuleCode = (~moduleName, ~endpoints, ~overrideDir=?) => {
     )
     ->Array.join("\n\n")
 
-  `
-    |${header->String.trimEnd}
-    |
-    |module ${moduleName} = {
-    |${body}
-    |}
-    |`->CodegenUtils.trimMargin
+  Handlebars.render(
+    Templates.moduleWrapped,
+    {
+      "header": header->String.trimEnd,
+      "moduleName": moduleName,
+      "body": body,
+    },
+  )
 }
 
 let internalGenerateIntegratedModule = (
@@ -220,13 +221,14 @@ let generateCombinedModule = (
     ~includeHeader=false,
   )
   
-  `
-    |${header->String.trimEnd}
-    |
-    |${shared}
-    |
-    |${extension}
-    |`->CodegenUtils.trimMargin
+  Handlebars.render(
+    Templates.combinedModule,
+    {
+      "header": header->String.trimEnd,
+      "shared": shared,
+      "extension": extension,
+    },
+  )
 }
 
 let generateTagModuleFiles = (~endpoints, ~outputDir, ~wrapInModule=false, ~overrideDir=?) => {

package/src/generators/SchemaCodeGenerator.res

@@ -75,10 +75,12 @@ let generateEndpointModule = (path, method, operation: Types.operation) => {
   }
   let schemasCode = generateOperationSchemas(operationId, operation)
 
-  `${docComment}module ${CodegenUtils.toPascalCase(operationId)} = {
-${schemasCode->CodegenUtils.indent(2)}
-
-  let endpoint = "${path}"
-  let method = #${methodStr}
-}`
+  Handlebars.render(Templates.endpointModule, {
+      "docComment": docComment,
+      "moduleName": CodegenUtils.toPascalCase(operationId),
+      "schemasCode": schemasCode->CodegenUtils.indent(2),
+      "path": path,
+      "methodStr": methodStr,
+    },
+  )
 }

package/src/generators/ThinWrapperGenerator.res

@@ -3,23 +3,14 @@
 // ThinWrapperGenerator.res - Generate ReScript thin wrappers with pipe-first ergonomics
 open Types
 
-let clientTypeCode = `
-  |type client = {
-  |  baseUrl: string,
-  |  token: option<string>,
-  |  fetch: ${CodegenUtils.fetchTypeSignature},
-  |}
-  |`->CodegenUtils.trimMargin
+let clientTypeCode =
+  Handlebars.render(Templates.clientType, {"fetchTypeSignature": CodegenUtils.fetchTypeSignature})
 
 let generateConnectFunction = (title) =>
-  `
-    |/** Create a client for ${title} */
-    |let connect = (~baseUrl: string, ~token: option<string>=?, ~fetch: ${CodegenUtils.fetchTypeSignature}, ()): client => {
-    |  baseUrl,
-    |  token,
-    |  fetch,
-    |}
-    |`->CodegenUtils.trimMargin
+  Handlebars.render(
+    Templates.connectFunction,
+    {"title": title, "fetchTypeSignature": CodegenUtils.fetchTypeSignature},
+  )
 
 let generateWrapperFunction = (~endpoint: endpoint, ~generatedModuleName: string) => {
   let operationName = CodegenUtils.generateOperationName(
@@ -41,8 +32,16 @@ let generateWrapperFunction = (~endpoint: endpoint, ~generatedModuleName: string
 
   let callArguments = hasRequestBody ? "~body=request, " : ""
 
-  `${docComment}  ${signature}: promise<${generatedModuleName}.${operationName}Response> => 
-    ${generatedModuleName}.${operationName}(${callArguments}~fetch=client.fetch)`
+  Handlebars.render(
+    Templates.wrapperFunction,
+    {
+      "docComment": docComment,
+      "signature": signature,
+      "generatedModuleName": generatedModuleName,
+      "operationName": operationName,
+      "callArguments": callArguments,
+    },
+  )
 }
 
 let generateWrapper = (
@@ -109,13 +108,14 @@ let generateWrapper = (
     })
     ->Array.join("\n\n")
 
-  let fileContent = `// Generated thin wrapper
-
-${clientTypeCode}
-
-${generateConnectFunction(spec.info.title)}
-
-${modulesCode}`
+  let fileContent = Handlebars.render(
+    Templates.wrapperFile,
+    {
+      "clientTypeCode": clientTypeCode,
+      "connectFunctionCode": generateConnectFunction(spec.info.title),
+      "modulesCode": modulesCode,
+    },
+  )
 
   Pipeline.fromFilesAndWarnings(
     [{path: FileSystem.makePath(outputDir, `${wrapperModuleName}.res`), content: fileContent}],