api-farmer 0.0.28 → 0.1.1

package/README.md

@@ -84,6 +84,7 @@ export default defineConfig({
     url() {},
     entity() {},
     fn() {},
+    comment() {},
     type() {},
     typeValue() {},
     typeQuery() {},
@@ -152,6 +153,11 @@ export interface Config {
    * Certain uncountable nouns that do not change from singular to plural
    */
   uncountableNouns?: string[]
+  /**
+   *  The options for the openapiTS library.
+   *  @see https://openapi-ts.dev/node
+   */
+  openapiTsOptions?: OpenAPITSOptions
 }
 ```
 
@@ -189,6 +195,10 @@ export interface ApiModule {
 }
 
 export interface ApiModulePayload {
+  /**
+   * The comment of the API endpoint, including summary, description, URL, and method.
+   */
+  comment: string
   /**
    * The name of the API function/dispatcher,
    * such as apiGetUsers, apiCreatePost, apiUpdateComment, etc.

package/dist/{chunk-56NOW5DM.js → chunk-2227C45C.js}

@@ -105,7 +105,7 @@ function getResponseMetadataItems(operation, validateStatus) {
   const validStatusResults = Object.keys(responses).sort((a, b) => Number(a) - Number(b)).filter((key) => validateStatus(Number(key))).map(Number);
   const metadataItems = validStatusResults.map((status) => {
     const content = operation.responses?.[status]?.content ?? {};
-    const responseContentType = findObjectKey(content, ["application/json", "*/*"]);
+    const responseContentType = findObjectKey(content, ["application/json", "application/octet-stream", "*/*"]);
     return {
       status,
       responseContentType

package/dist/{chunk-XM2F7GOE.js → chunk-P3SVS555.js}

@@ -6,7 +6,7 @@ import {
   isRequiredRequestBody,
   readSchema,
   readTemplateFile
-} from "./chunk-56NOW5DM.js";
+} from "./chunk-2227C45C.js";
 
 // src/generate.ts
 import { resolve } from "path";
@@ -16,6 +16,7 @@ import openapiTS, { astToString } from "openapi-typescript";
 import prettier from "prettier";
 import { groupBy, isArray, merge } from "rattail";
 import { logger } from "rslog";
+import ts from "typescript";
 
 // src/config.ts
 import { loadConfig } from "unconfig";
@@ -42,6 +43,22 @@ function transformModuleName({ name }) {
 function transformUrl({ path }) {
   return path.replace(/{/g, ":").replace(/}/g, "");
 }
+function transformComment({
+  summary,
+  description,
+  path,
+  method
+}) {
+  return `
+  /**${summary ? `
+* ${summary}` : ""}${description && summary !== description ? `
+* @description ${description}
+*` : ""}
+   * @url ${path}
+   * @method ${method.toLocaleUpperCase()}
+   */
+  `.trim();
+}
 function transformVerb({ method }) {
   switch (method) {
     case "post":
@@ -113,6 +130,7 @@ function createTransformer() {
     moduleName: transformModuleName,
     verb: transformVerb,
     url: transformUrl,
+    comment: transformComment,
     entity: transformEntity,
     fn: transformFn,
     type: transformType,
@@ -134,6 +152,7 @@ function transformPayloads(pathItems, options) {
     const args = { path, base, fullPath, url, method, uncountableNouns, operation };
     const entity = transformer.entity(args);
     const verb = transformer.verb(args);
+    const comment = transformer.comment({ ...args, ...operation });
     const requestContentType = operation.requestBody ? getRequestBodyContentType(operation.requestBody) : void 0;
     const responseMetadataItems = getResponseMetadataItems(operation, validateStatus);
     const fn = transformer.fn({ ...args, verb, entity });
@@ -153,6 +172,7 @@ function transformPayloads(pathItems, options) {
     const typeResponseBody = transformer.typeResponseBody({ ...args, type, verb, entity });
     const typeResponseBodyValue = responseMetadataItems.length > 0 ? transformer.typeResponseBodyValue({ ...args, type, verb, entity, responseMetadataItems }) : "undefined";
     payloads.push({
+      comment,
       fn,
       url,
       method,
@@ -198,7 +218,7 @@ function partitionApiModules(schema, options) {
   return apiModules;
 }
 function renderApiModules(apiModules, options) {
-  const { output, ts, typesOnly, overrides, preset } = options;
+  const { output, ts: ts2, typesOnly, overrides, preset } = options;
   const templateFile = readTemplateFile(preset);
   const typesFilename = options.typesFilename.replace(".ts", "");
   return Promise.all(
@@ -207,7 +227,7 @@ function renderApiModules(apiModules, options) {
         const data = {
           apiModule,
           typesFilename,
-          ts,
+          ts: ts2,
           typesOnly
         };
         prettier.format(ejs.render(templateFile, data), {
@@ -216,7 +236,7 @@ function renderApiModules(apiModules, options) {
           singleQuote: true,
           printWidth: 120
         }).then((content) => {
-          const path = resolve(output, `${apiModule.name}.${ts ? "ts" : "js"}`);
+          const path = resolve(output, `${apiModule.name}.${ts2 ? "ts" : "js"}`);
           const shouldSkip = (!overrides || isArray(overrides) && !overrides.includes(apiModule.name)) && fse.existsSync(path);
           if (shouldSkip) {
             logger.warn(`File already exists, skip: ${path}`);
@@ -231,9 +251,17 @@ function renderApiModules(apiModules, options) {
     )
   );
 }
-async function generateTypes(schema, output, typesFilename) {
+async function generateTypes(schema, output, typesFilename, openapiTsOptions) {
+  const BLOB = ts.factory.createTypeReferenceNode(ts.factory.createIdentifier("Blob"));
+  const NULL = ts.factory.createLiteralTypeNode(ts.factory.createNull());
   const ast = await openapiTS(schema, {
-    defaultNonNullable: false
+    defaultNonNullable: false,
+    transform(schemaObject) {
+      if (schemaObject.format === "binary") {
+        return schemaObject.nullable ? ts.factory.createUnionTypeNode([BLOB, NULL]) : BLOB;
+      }
+    },
+    ...openapiTsOptions
   });
   const contents = astToString(ast);
   const typesFilepath = resolve(CWD, output, typesFilename);
@@ -245,7 +273,7 @@ async function generate(userOptions = {}) {
   const options = merge(config, userOptions);
   const {
     base,
-    ts = true,
+    ts: ts2 = true,
     typesOnly = false,
     overrides = true,
     preset = "axle",
@@ -254,13 +282,14 @@ async function generate(userOptions = {}) {
     typesFilename = "_types.ts",
     validateStatus = (status) => status >= 200 && status < 300,
     transformer = {},
-    uncountableNouns = []
+    uncountableNouns = [],
+    openapiTsOptions = {}
   } = options;
   const mergedTransformer = { ...createTransformer(), ...transformer };
   const schema = await readSchema(input);
   logger.info("Generating API modules...");
-  if (ts) {
-    await generateTypes(schema, output, typesFilename);
+  if (ts2) {
+    await generateTypes(schema, output, typesFilename, openapiTsOptions);
   }
   const apiModules = partitionApiModules(schema, {
     base,
@@ -268,7 +297,7 @@ async function generate(userOptions = {}) {
     transformer: mergedTransformer,
     validateStatus
   });
-  await renderApiModules(apiModules, { output, typesFilename, ts, typesOnly, overrides, preset });
+  await renderApiModules(apiModules, { output, typesFilename, ts: ts2, typesOnly, overrides, preset });
   logger.success("Done");
 }
 
@@ -277,6 +306,7 @@ export {
   getConfig,
   transformModuleName,
   transformUrl,
+  transformComment,
   transformVerb,
   transformEntity,
   transformFn,

package/dist/cli.cjs

@@ -102,7 +102,7 @@ function getResponseMetadataItems(operation, validateStatus) {
   const validStatusResults = Object.keys(responses).sort((a, b) => Number(a) - Number(b)).filter((key) => validateStatus(Number(key))).map(Number);
   const metadataItems = validStatusResults.map((status) => {
     const content = operation.responses?.[status]?.content ?? {};
-    const responseContentType = findObjectKey(content, ["application/json", "*/*"]);
+    const responseContentType = findObjectKey(content, ["application/json", "application/octet-stream", "*/*"]);
     return {
       status,
       responseContentType
@@ -153,6 +153,22 @@ function transformModuleName({ name }) {
 function transformUrl({ path }) {
   return path.replace(/{/g, ":").replace(/}/g, "");
 }
+function transformComment({
+  summary,
+  description,
+  path,
+  method
+}) {
+  return `
+  /**${summary ? `
+* ${summary}` : ""}${description && summary !== description ? `
+* @description ${description}
+*` : ""}
+   * @url ${path}
+   * @method ${method.toLocaleUpperCase()}
+   */
+  `.trim();
+}
 function transformVerb({ method }) {
   switch (method) {
     case "post":
@@ -224,6 +240,7 @@ function createTransformer() {
     moduleName: transformModuleName,
     verb: transformVerb,
     url: transformUrl,
+    comment: transformComment,
     entity: transformEntity,
     fn: transformFn,
     type: transformType,
@@ -262,6 +279,7 @@ function transformPayloads(pathItems, options) {
     const args = { path, base, fullPath, url, method, uncountableNouns, operation };
     const entity = transformer.entity(args);
     const verb = transformer.verb(args);
+    const comment = transformer.comment({ ...args, ...operation });
     const requestContentType = operation.requestBody ? getRequestBodyContentType(operation.requestBody) : void 0;
     const responseMetadataItems = getResponseMetadataItems(operation, validateStatus);
     const fn = transformer.fn({ ...args, verb, entity });
@@ -281,6 +299,7 @@ function transformPayloads(pathItems, options) {
     const typeResponseBody = transformer.typeResponseBody({ ...args, type, verb, entity });
     const typeResponseBodyValue = responseMetadataItems.length > 0 ? transformer.typeResponseBodyValue({ ...args, type, verb, entity, responseMetadataItems }) : "undefined";
     payloads.push({
+      comment,
       fn,
       url,
       method,
@@ -326,7 +345,7 @@ function partitionApiModules(schema, options) {
   return apiModules;
 }
 function renderApiModules(apiModules, options) {
-  const { output, ts, typesOnly, overrides, preset } = options;
+  const { output, ts: ts2, typesOnly, overrides, preset } = options;
   const templateFile = readTemplateFile(preset);
   const typesFilename = options.typesFilename.replace(".ts", "");
   return Promise.all(
@@ -335,7 +354,7 @@ function renderApiModules(apiModules, options) {
         const data = {
           apiModule,
           typesFilename,
-          ts,
+          ts: ts2,
           typesOnly
         };
         import_prettier.default.format(import_ejs.default.render(templateFile, data), {
@@ -344,7 +363,7 @@ function renderApiModules(apiModules, options) {
           singleQuote: true,
           printWidth: 120
         }).then((content) => {
-          const path = (0, import_path3.resolve)(output, `${apiModule.name}.${ts ? "ts" : "js"}`);
+          const path = (0, import_path3.resolve)(output, `${apiModule.name}.${ts2 ? "ts" : "js"}`);
           const shouldSkip = (!overrides || (0, import_rattail3.isArray)(overrides) && !overrides.includes(apiModule.name)) && import_fs_extra2.default.existsSync(path);
           if (shouldSkip) {
             import_rslog2.logger.warn(`File already exists, skip: ${path}`);
@@ -359,9 +378,17 @@ function renderApiModules(apiModules, options) {
     )
   );
 }
-async function generateTypes(schema, output, typesFilename) {
+async function generateTypes(schema, output, typesFilename, openapiTsOptions) {
+  const BLOB = import_typescript.default.factory.createTypeReferenceNode(import_typescript.default.factory.createIdentifier("Blob"));
+  const NULL = import_typescript.default.factory.createLiteralTypeNode(import_typescript.default.factory.createNull());
   const ast = await (0, import_openapi_typescript.default)(schema, {
-    defaultNonNullable: false
+    defaultNonNullable: false,
+    transform(schemaObject) {
+      if (schemaObject.format === "binary") {
+        return schemaObject.nullable ? import_typescript.default.factory.createUnionTypeNode([BLOB, NULL]) : BLOB;
+      }
+    },
+    ...openapiTsOptions
   });
   const contents = (0, import_openapi_typescript.astToString)(ast);
   const typesFilepath = (0, import_path3.resolve)(CWD, output, typesFilename);
@@ -373,7 +400,7 @@ async function generate(userOptions = {}) {
   const options = (0, import_rattail3.merge)(config, userOptions);
   const {
     base,
-    ts = true,
+    ts: ts2 = true,
     typesOnly = false,
     overrides = true,
     preset = "axle",
@@ -382,13 +409,14 @@ async function generate(userOptions = {}) {
     typesFilename = "_types.ts",
     validateStatus = (status) => status >= 200 && status < 300,
     transformer = {},
-    uncountableNouns = []
+    uncountableNouns = [],
+    openapiTsOptions = {}
   } = options;
   const mergedTransformer = { ...createTransformer(), ...transformer };
   const schema = await readSchema(input);
   import_rslog2.logger.info("Generating API modules...");
-  if (ts) {
-    await generateTypes(schema, output, typesFilename);
+  if (ts2) {
+    await generateTypes(schema, output, typesFilename, openapiTsOptions);
   }
   const apiModules = partitionApiModules(schema, {
     base,
@@ -396,10 +424,10 @@ async function generate(userOptions = {}) {
     transformer: mergedTransformer,
     validateStatus
   });
-  await renderApiModules(apiModules, { output, typesFilename, ts, typesOnly, overrides, preset });
+  await renderApiModules(apiModules, { output, typesFilename, ts: ts2, typesOnly, overrides, preset });
   import_rslog2.logger.success("Done");
 }
-var import_path3, import_ejs, import_fs_extra2, import_openapi_typescript, import_prettier, import_rattail3, import_rslog2;
+var import_path3, import_ejs, import_fs_extra2, import_openapi_typescript, import_prettier, import_rattail3, import_rslog2, import_typescript;
 var init_generate = __esm({
   "src/generate.ts"() {
     "use strict";
@@ -411,6 +439,7 @@ var init_generate = __esm({
     import_prettier = __toESM(require("prettier"), 1);
     import_rattail3 = require("rattail");
     import_rslog2 = require("rslog");
+    import_typescript = __toESM(require("typescript"), 1);
     init_config();
     init_constants();
     init_transformer();

package/dist/cli.js

@@ -1,14 +1,14 @@
 #!/usr/bin/env node
 import {
   getCliVersion
-} from "./chunk-56NOW5DM.js";
+} from "./chunk-2227C45C.js";
 
 // src/cli.ts
 import { Command } from "commander";
 var program = new Command();
 program.version(getCliVersion());
 program.action(async () => {
-  const { generate } = await import("./generate-NRJ4NQ4O.js");
+  const { generate } = await import("./generate-WIU5E7EL.js");
   return generate();
 });
 program.parse();

package/dist/{generate-NRJ4NQ4O.js → generate-WIU5E7EL.js}

@@ -4,8 +4,8 @@ import {
   partitionApiModules,
   renderApiModules,
   transformPayloads
-} from "./chunk-XM2F7GOE.js";
-import "./chunk-56NOW5DM.js";
+} from "./chunk-P3SVS555.js";
+import "./chunk-2227C45C.js";
 export {
   generate,
   generateTypes,

package/dist/index.cjs

@@ -49,6 +49,7 @@ __export(index_exports, {
   readSchemaContent: () => readSchemaContent,
   readTemplateFile: () => readTemplateFile,
   renderApiModules: () => renderApiModules,
+  transformComment: () => transformComment,
   transformEntity: () => transformEntity,
   transformFn: () => transformFn,
   transformModuleName: () => transformModuleName,
@@ -75,6 +76,22 @@ function transformModuleName({ name }) {
 function transformUrl({ path }) {
   return path.replace(/{/g, ":").replace(/}/g, "");
 }
+function transformComment({
+  summary,
+  description,
+  path,
+  method
+}) {
+  return `
+  /**${summary ? `
+* ${summary}` : ""}${description && summary !== description ? `
+* @description ${description}
+*` : ""}
+   * @url ${path}
+   * @method ${method.toLocaleUpperCase()}
+   */
+  `.trim();
+}
 function transformVerb({ method }) {
   switch (method) {
     case "post":
@@ -146,6 +163,7 @@ function createTransformer() {
     moduleName: transformModuleName,
     verb: transformVerb,
     url: transformUrl,
+    comment: transformComment,
     entity: transformEntity,
     fn: transformFn,
     type: transformType,
@@ -167,6 +185,7 @@ var import_openapi_typescript = __toESM(require("openapi-typescript"), 1);
 var import_prettier = __toESM(require("prettier"), 1);
 var import_rattail3 = require("rattail");
 var import_rslog2 = require("rslog");
+var import_typescript = __toESM(require("typescript"), 1);
 
 // src/config.ts
 var import_unconfig = require("unconfig");
@@ -284,7 +303,7 @@ function getResponseMetadataItems(operation, validateStatus) {
   const validStatusResults = Object.keys(responses).sort((a, b) => Number(a) - Number(b)).filter((key) => validateStatus(Number(key))).map(Number);
   const metadataItems = validStatusResults.map((status) => {
     const content = operation.responses?.[status]?.content ?? {};
-    const responseContentType = findObjectKey(content, ["application/json", "*/*"]);
+    const responseContentType = findObjectKey(content, ["application/json", "application/octet-stream", "*/*"]);
     return {
       status,
       responseContentType
@@ -301,6 +320,7 @@ function transformPayloads(pathItems, options) {
     const args = { path, base, fullPath, url, method, uncountableNouns, operation };
     const entity = transformer.entity(args);
     const verb = transformer.verb(args);
+    const comment = transformer.comment({ ...args, ...operation });
     const requestContentType = operation.requestBody ? getRequestBodyContentType(operation.requestBody) : void 0;
     const responseMetadataItems = getResponseMetadataItems(operation, validateStatus);
     const fn = transformer.fn({ ...args, verb, entity });
@@ -320,6 +340,7 @@ function transformPayloads(pathItems, options) {
     const typeResponseBody = transformer.typeResponseBody({ ...args, type, verb, entity });
     const typeResponseBodyValue = responseMetadataItems.length > 0 ? transformer.typeResponseBodyValue({ ...args, type, verb, entity, responseMetadataItems }) : "undefined";
     payloads.push({
+      comment,
       fn,
       url,
       method,
@@ -365,7 +386,7 @@ function partitionApiModules(schema, options) {
   return apiModules;
 }
 function renderApiModules(apiModules, options) {
-  const { output, ts, typesOnly, overrides, preset } = options;
+  const { output, ts: ts2, typesOnly, overrides, preset } = options;
   const templateFile = readTemplateFile(preset);
   const typesFilename = options.typesFilename.replace(".ts", "");
   return Promise.all(
@@ -374,7 +395,7 @@ function renderApiModules(apiModules, options) {
         const data = {
           apiModule,
           typesFilename,
-          ts,
+          ts: ts2,
           typesOnly
         };
         import_prettier.default.format(import_ejs.default.render(templateFile, data), {
@@ -383,7 +404,7 @@ function renderApiModules(apiModules, options) {
           singleQuote: true,
           printWidth: 120
         }).then((content) => {
-          const path = (0, import_path3.resolve)(output, `${apiModule.name}.${ts ? "ts" : "js"}`);
+          const path = (0, import_path3.resolve)(output, `${apiModule.name}.${ts2 ? "ts" : "js"}`);
           const shouldSkip = (!overrides || (0, import_rattail3.isArray)(overrides) && !overrides.includes(apiModule.name)) && import_fs_extra2.default.existsSync(path);
           if (shouldSkip) {
             import_rslog2.logger.warn(`File already exists, skip: ${path}`);
@@ -398,9 +419,17 @@ function renderApiModules(apiModules, options) {
     )
   );
 }
-async function generateTypes(schema, output, typesFilename) {
+async function generateTypes(schema, output, typesFilename, openapiTsOptions) {
+  const BLOB = import_typescript.default.factory.createTypeReferenceNode(import_typescript.default.factory.createIdentifier("Blob"));
+  const NULL = import_typescript.default.factory.createLiteralTypeNode(import_typescript.default.factory.createNull());
   const ast = await (0, import_openapi_typescript.default)(schema, {
-    defaultNonNullable: false
+    defaultNonNullable: false,
+    transform(schemaObject) {
+      if (schemaObject.format === "binary") {
+        return schemaObject.nullable ? import_typescript.default.factory.createUnionTypeNode([BLOB, NULL]) : BLOB;
+      }
+    },
+    ...openapiTsOptions
   });
   const contents = (0, import_openapi_typescript.astToString)(ast);
   const typesFilepath = (0, import_path3.resolve)(CWD, output, typesFilename);
@@ -412,7 +441,7 @@ async function generate(userOptions = {}) {
   const options = (0, import_rattail3.merge)(config, userOptions);
   const {
     base,
-    ts = true,
+    ts: ts2 = true,
     typesOnly = false,
     overrides = true,
     preset = "axle",
@@ -421,13 +450,14 @@ async function generate(userOptions = {}) {
     typesFilename = "_types.ts",
     validateStatus = (status) => status >= 200 && status < 300,
     transformer = {},
-    uncountableNouns = []
+    uncountableNouns = [],
+    openapiTsOptions = {}
   } = options;
   const mergedTransformer = { ...createTransformer(), ...transformer };
   const schema = await readSchema(input);
   import_rslog2.logger.info("Generating API modules...");
-  if (ts) {
-    await generateTypes(schema, output, typesFilename);
+  if (ts2) {
+    await generateTypes(schema, output, typesFilename, openapiTsOptions);
   }
   const apiModules = partitionApiModules(schema, {
     base,
@@ -435,7 +465,7 @@ async function generate(userOptions = {}) {
     transformer: mergedTransformer,
     validateStatus
   });
-  await renderApiModules(apiModules, { output, typesFilename, ts, typesOnly, overrides, preset });
+  await renderApiModules(apiModules, { output, typesFilename, ts: ts2, typesOnly, overrides, preset });
   import_rslog2.logger.success("Done");
 }
 
@@ -462,6 +492,7 @@ var import_pluralize2 = __toESM(require("pluralize"), 1);
   readSchemaContent,
   readTemplateFile,
   renderApiModules,
+  transformComment,
   transformEntity,
   transformFn,
   transformModuleName,

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { OpenAPI3, RequestBodyObject, ReferenceObject, OperationObject } from 'openapi-typescript';
+import { OpenAPI3, RequestBodyObject, ReferenceObject, OperationObject, OpenAPITSOptions } from 'openapi-typescript';
 export { default as pluralize } from 'pluralize';
 
 type Preset = 'axle' | 'axios';
@@ -69,6 +69,12 @@ declare function transformUrl({ path }: {
     fullPath: string;
     base: string | undefined;
 }): string;
+declare function transformComment({ summary, description, path, method, }: {
+    summary?: string;
+    description?: string;
+    path: string;
+    method: string;
+} & TransformerBaseArgs): string;
 declare function transformVerb({ method }: {
     method: string;
 }): string;
@@ -122,6 +128,7 @@ interface Transformer {
     moduleName: typeof transformModuleName;
     verb: typeof transformVerb;
     url: typeof transformUrl;
+    comment: typeof transformComment;
     entity: typeof transformEntity;
     fn: typeof transformFn;
     type: typeof transformType;
@@ -164,6 +171,10 @@ interface ApiModule {
     payloads: ApiModulePayload[];
 }
 interface ApiModulePayload {
+    /**
+     * The comment of the API endpoint, including summary, description, URL, and method.
+     */
+    comment: string;
     /**
      * The name of the API function/dispatcher, such as apiGetUsers, apiCreatePost, apiUpdateComment, etc.
      */
@@ -274,6 +285,10 @@ interface GenerateOptions {
      * Certain uncountable nouns that do not change from singular to plural
      */
     uncountableNouns?: string[];
+    /**
+     *  A function to transform the generated types AST before printing to string.
+     */
+    openapiTsOptions?: OpenAPITSOptions;
 }
 declare function transformPayloads(pathItems: Record<string, OperationObject>, options: {
     path: string;
@@ -297,11 +312,11 @@ declare function renderApiModules(apiModules: ApiModule[], options: {
     overrides: boolean | string[];
     preset: Preset;
 }): Promise<unknown[]>;
-declare function generateTypes(schema: OpenAPI3, output: string, typesFilename: string): Promise<void>;
+declare function generateTypes(schema: OpenAPI3, output: string, typesFilename: string, openapiTsOptions: OpenAPITSOptions): Promise<void>;
 declare function generate(userOptions?: GenerateOptions): Promise<void>;
 
 type Config = GenerateOptions;
 declare function defineConfig(config: Config): GenerateOptions;
 declare function getConfig(): Promise<Config>;
 
-export { type ApiModule, type ApiModulePayload, type ApiModuleTemplateData, type Config, type GenerateOptions, type Preset, type ResponseMetadataItem, type StatusCodeStrategy, type StatusCodes, type Transformer, type TransformerBaseArgs, createStatusCodesByStrategy, createTransformer, defineConfig, findObjectKey, generate, generateTypes, getCliVersion, getConfig, getRequestBodyContentType, getResponseMetadataItems, getSchemaNode, isRemoteSchema, isRequiredRequestBody, partitionApiModules, readSchema, readSchemaContent, readTemplateFile, renderApiModules, transformEntity, transformFn, transformModuleName, transformPayloads, transformType, transformTypeQuery, transformTypeQueryValue, transformTypeRequestBody, transformTypeRequestBodyValue, transformTypeResponseBody, transformTypeResponseBodyValue, transformTypeValue, transformUrl, transformVerb };
+export { type ApiModule, type ApiModulePayload, type ApiModuleTemplateData, type Config, type GenerateOptions, type Preset, type ResponseMetadataItem, type StatusCodeStrategy, type StatusCodes, type Transformer, type TransformerBaseArgs, createStatusCodesByStrategy, createTransformer, defineConfig, findObjectKey, generate, generateTypes, getCliVersion, getConfig, getRequestBodyContentType, getResponseMetadataItems, getSchemaNode, isRemoteSchema, isRequiredRequestBody, partitionApiModules, readSchema, readSchemaContent, readTemplateFile, renderApiModules, transformComment, transformEntity, transformFn, transformModuleName, transformPayloads, transformType, transformTypeQuery, transformTypeQueryValue, transformTypeRequestBody, transformTypeRequestBodyValue, transformTypeResponseBody, transformTypeResponseBodyValue, transformTypeValue, transformUrl, transformVerb };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { OpenAPI3, RequestBodyObject, ReferenceObject, OperationObject } from 'openapi-typescript';
+import { OpenAPI3, RequestBodyObject, ReferenceObject, OperationObject, OpenAPITSOptions } from 'openapi-typescript';
 export { default as pluralize } from 'pluralize';
 
 type Preset = 'axle' | 'axios';
@@ -69,6 +69,12 @@ declare function transformUrl({ path }: {
     fullPath: string;
     base: string | undefined;
 }): string;
+declare function transformComment({ summary, description, path, method, }: {
+    summary?: string;
+    description?: string;
+    path: string;
+    method: string;
+} & TransformerBaseArgs): string;
 declare function transformVerb({ method }: {
     method: string;
 }): string;
@@ -122,6 +128,7 @@ interface Transformer {
     moduleName: typeof transformModuleName;
     verb: typeof transformVerb;
     url: typeof transformUrl;
+    comment: typeof transformComment;
     entity: typeof transformEntity;
     fn: typeof transformFn;
     type: typeof transformType;
@@ -164,6 +171,10 @@ interface ApiModule {
     payloads: ApiModulePayload[];
 }
 interface ApiModulePayload {
+    /**
+     * The comment of the API endpoint, including summary, description, URL, and method.
+     */
+    comment: string;
     /**
      * The name of the API function/dispatcher, such as apiGetUsers, apiCreatePost, apiUpdateComment, etc.
      */
@@ -274,6 +285,10 @@ interface GenerateOptions {
      * Certain uncountable nouns that do not change from singular to plural
      */
     uncountableNouns?: string[];
+    /**
+     *  A function to transform the generated types AST before printing to string.
+     */
+    openapiTsOptions?: OpenAPITSOptions;
 }
 declare function transformPayloads(pathItems: Record<string, OperationObject>, options: {
     path: string;
@@ -297,11 +312,11 @@ declare function renderApiModules(apiModules: ApiModule[], options: {
     overrides: boolean | string[];
     preset: Preset;
 }): Promise<unknown[]>;
-declare function generateTypes(schema: OpenAPI3, output: string, typesFilename: string): Promise<void>;
+declare function generateTypes(schema: OpenAPI3, output: string, typesFilename: string, openapiTsOptions: OpenAPITSOptions): Promise<void>;
 declare function generate(userOptions?: GenerateOptions): Promise<void>;
 
 type Config = GenerateOptions;
 declare function defineConfig(config: Config): GenerateOptions;
 declare function getConfig(): Promise<Config>;
 
-export { type ApiModule, type ApiModulePayload, type ApiModuleTemplateData, type Config, type GenerateOptions, type Preset, type ResponseMetadataItem, type StatusCodeStrategy, type StatusCodes, type Transformer, type TransformerBaseArgs, createStatusCodesByStrategy, createTransformer, defineConfig, findObjectKey, generate, generateTypes, getCliVersion, getConfig, getRequestBodyContentType, getResponseMetadataItems, getSchemaNode, isRemoteSchema, isRequiredRequestBody, partitionApiModules, readSchema, readSchemaContent, readTemplateFile, renderApiModules, transformEntity, transformFn, transformModuleName, transformPayloads, transformType, transformTypeQuery, transformTypeQueryValue, transformTypeRequestBody, transformTypeRequestBodyValue, transformTypeResponseBody, transformTypeResponseBodyValue, transformTypeValue, transformUrl, transformVerb };
+export { type ApiModule, type ApiModulePayload, type ApiModuleTemplateData, type Config, type GenerateOptions, type Preset, type ResponseMetadataItem, type StatusCodeStrategy, type StatusCodes, type Transformer, type TransformerBaseArgs, createStatusCodesByStrategy, createTransformer, defineConfig, findObjectKey, generate, generateTypes, getCliVersion, getConfig, getRequestBodyContentType, getResponseMetadataItems, getSchemaNode, isRemoteSchema, isRequiredRequestBody, partitionApiModules, readSchema, readSchemaContent, readTemplateFile, renderApiModules, transformComment, transformEntity, transformFn, transformModuleName, transformPayloads, transformType, transformTypeQuery, transformTypeQueryValue, transformTypeRequestBody, transformTypeRequestBodyValue, transformTypeResponseBody, transformTypeResponseBodyValue, transformTypeValue, transformUrl, transformVerb };

package/dist/index.js

@@ -6,6 +6,7 @@ import {
   getConfig,
   partitionApiModules,
   renderApiModules,
+  transformComment,
   transformEntity,
   transformFn,
   transformModuleName,
@@ -20,7 +21,7 @@ import {
   transformTypeValue,
   transformUrl,
   transformVerb
-} from "./chunk-XM2F7GOE.js";
+} from "./chunk-P3SVS555.js";
 import {
   createStatusCodesByStrategy,
   findObjectKey,
@@ -33,7 +34,7 @@ import {
   readSchema,
   readSchemaContent,
   readTemplateFile
-} from "./chunk-56NOW5DM.js";
+} from "./chunk-2227C45C.js";
 
 // src/index.ts
 import { default as default2 } from "pluralize";
@@ -57,6 +58,7 @@ export {
   readSchemaContent,
   readTemplateFile,
   renderApiModules,
+  transformComment,
   transformEntity,
   transformFn,
   transformModuleName,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "api-farmer",
-  "version": "0.0.28",
+  "version": "0.1.1",
   "description": "API module generation tool based on Openapi3/Swagger2.",
   "keywords": [
     "cli",
@@ -55,21 +55,21 @@
     "fs-extra": "^11.2.0",
     "openapi-typescript": "^7.5.2",
     "pluralize": "^8.0.0",
+    "prettier": "^3.4.2",
     "rattail": "^1.0.19",
     "rslog": "^1.2.3",
     "swagger2openapi": "^7.0.8",
     "unconfig": "^0.6.0",
-    "yaml": "^2.7.0",
-    "prettier": "^3.4.2"
+    "yaml": "^2.7.0"
   },
   "devDependencies": {
-    "@configurajs/eslint": "^0.1.0",
-    "@configurajs/prettier": "^0.1.1",
+    "@configurajs/eslint": "^0.1.2",
+    "@configurajs/prettier": "^0.1.4",
     "@types/ejs": "^3.1.5",
     "@types/fs-extra": "^11.0.4",
     "@types/node": "^22.8.1",
     "@types/swagger2openapi": "^7.0.4",
-    "@varlet/release": "^0.3.1",
+    "@varlet/release": "^0.4.1",
     "eslint": "^9.17.0",
     "nano-staged": "0.8.0",
     "rimraf": "^6.0.1",
@@ -78,7 +78,7 @@
     "typescript": "5.3.3"
   },
   "peerDependencies": {
-    "eslint": "^9.17.0"
+    "typescript": "^5.3.3"
   },
   "engines": {
     "pnpm": ">=9.0"
@@ -88,8 +88,8 @@
     "clean": "rimraf node_modules dist",
     "dev": "tsup src/index.ts src/cli.ts --format esm,cjs --watch --dts --shims",
     "format": "prettier --write .",
+    "gen": "rimraf ./fixtures/axios/src/apis/generated ./fixtures/axle/src/apis/generated && pnpm --dir ./fixtures/axios gen & pnpm --dir ./fixtures/axle gen",
     "lint": "eslint . --fix",
-    "release": "pnpm build && vr release",
-    "gen": "rimraf ./fixtures/axios/src/apis/generated ./fixtures/axle/src/apis/generated && pnpm --dir ./fixtures/axios gen & pnpm --dir ./fixtures/axle gen"
+    "release": "pnpm build && vr release"
   }
 }

package/templates/axios.ejs

@@ -4,6 +4,7 @@
 
 <%_ if (!typesOnly) { _%>
   <% apiModule.payloads.forEach(payload => { %> %>
+    <%- payload.comment %>
     export const <%- payload.fn %> = 
       (config<% if (ts) { %>: RequestConfig<<%- payload.typeQuery %>, <%- payload.typeRequestBody %>> <% } %> = {}) => request
         <% if (ts) { %><<%- payload.typeResponseBody %>><% } %>({

package/templates/axle.ejs

@@ -3,6 +3,7 @@
 
 <% if (!typesOnly) { %>
   <% apiModule.payloads.forEach(payload => { %> %>
+    <%- payload.comment %>
     export const <%- payload.fn %> = api
 
     <% if (ts) { %>