api-farmer 0.0.3 → 0.0.5

package/README.md

@@ -0,0 +1,270 @@
+# api-farmer
+
+### Intro
+
+API module generation tool based on `Openapi3/Swagger2`.
+
+### Features
+
+- 🌐   Supports generating all API modules from `OpenAPI3/Swagger2 schemas`
+- 📦   Supports generating `ts/js` modules
+- 🛠️   Comprehensive `ts type` generation
+- ✏️   Supports custom `ejs` templates for tailored content generation
+- 🔄   Allows using a `transformer` to modify all variables in templates for fine-grained customization
+- 💻   Supports both `cli` and `node.js api`
+- 📋   Includes built-in presets for [axle](https://github.com/varletjs/axle) and [axios](https://axios-http.com/docs/intro) templates
+
+### Quick Start
+
+#### 1. Installation
+
+```shell
+# npm
+npm i api-farmer -D
+# yarn
+yarn add api-farmer -D
+# pnpm
+pnpm i api-farmer -D
+```
+
+#### 2. Setup
+
+```ts
+// in project root path api-farmer.config.ts or api-farmer.config.js
+import { defineConfig } from 'api-farmer'
+
+export default defineConfig({
+  // openapi or swagger schema path, defaults './schema.json'
+  input: './schema.yaml',
+  // generated codes output path, defaults './src/apis'
+  output: './src/apis',
+  // 'axle' or 'axios', defaults 'axle'.
+  preset: 'axios',
+})
+```
+
+#### 3. Run Command
+
+```shell
+npx af
+```
+
+> [!TIP]
+> The generated content does not include the integration of the request client.
+
+#### Some Examples
+
+Some simple usage examples can be found [here](fixtures)
+
+### Custom EJS Template
+
+Create `api-farmer.ejs` in the project root, which will replace the `preset` template.
+The template format can refer to the preset template listed below:
+
+- [Axle](templates/axle.ejs)
+- [Axios](templates/axios.ejs)
+
+See the bottom of the document for template variable definitions.
+
+### Status Code Strategy
+
+`Restful API` recommends using different successful http status codes for different methods, such as `get: 200`, `post: 201`, etc. If you don't need this strategy, you can set `statusCodeStrategy` to `loose`
+
+```ts
+// api-farmer.config.ts
+import { defineConfig } from 'api-farmer'
+
+export default defineConfig({
+  // 'strict' or 'loose', defaults 'strict'
+  statusCodeStrategy: 'loose',
+})
+```
+
+### Transformer API
+
+You can use the Transformer API to further define template variables, which will override the default transformation rules.
+
+```ts
+// api-farmer.config.ts
+import { defineConfig } from 'api-farmer'
+
+export default defineConfig({
+  transformer: {
+    moduleName({ name }) {
+      // The new module name.
+      return `${name}.generated`
+    },
+    verb() {},
+    url() {},
+    entity() {},
+    fn() {},
+    type() {},
+    typeValue() {},
+    typeQuery() {},
+    typeQueryValue() {},
+    typeRequestBody() {},
+    typeRequestBodyValue() {},
+    typeResponseBody() {},
+    typeResponseBodyValue() {},
+  },
+})
+```
+
+### Configuration Options
+
+```ts
+export interface Config {
+  /**
+   * The path to the OpenAPI/Swagger schema file.
+   */
+  input?: string
+  /**
+   * The path to the output directory.
+   */
+  output?: string
+  /**
+   * The base path of the API endpoints.
+   */
+  base?: string
+  /**
+   * The filename of the generated openapi types file.
+   */
+  typesFilename?: string
+  /**
+   * The transformer api options, used to override the default transformation rules.
+   */
+  transformer?: Partial<Transformer>
+  /**
+   * Whether to generate TypeScript code.
+   */
+  ts?: boolean
+  /**
+   * Whether to override the existing files, or an array of filenames to override.
+   */
+  overrides?: boolean | string[]
+  /**
+   * The preset ejs template to use.
+   */
+  preset?: Preset
+  /**
+   * The status code strategy to use.
+   * loose: all success status codes are 200, strict: use the openapi recommended success status codes.
+   */
+  statusCodeStrategy?: StatusCodeStrategy
+  /**
+   * The status codes to override the default status codes.
+   */
+  statusCodes?: {
+    get?: number
+    post?: number
+    put?: number
+    delete?: number
+    patch?: number
+    options?: number
+    head?: number
+  }
+}
+```
+
+### Template Variable Definitions
+
+```ts
+export interface ApiModuleTemplateData {
+  /**
+   * API module metadata
+   */
+  apiModule: ApiModule
+  /**
+   * The name of the generated api ts type aggregation file
+   */
+  typesFilename: string
+  /**
+   * Whether to generate ts code
+   */
+  ts: boolean
+}
+
+export interface ApiModule {
+  /**
+   * The name of the API module
+   */
+  name: string
+  /**
+   * API module payloads
+   */
+  payloads: ApiModulePayload[]
+}
+
+export interface ApiModulePayload {
+  /**
+   * The name of the API function/dispatcher,
+   * such as apiGetUsers, apiCreatePost, apiUpdateComment, etc.
+   */
+  fn: string
+  /**
+   * The URL of the API endpoint,
+   * such as /users, /posts, /comments, etc.
+   */
+  url: string
+  /**
+   * The HTTP method of the API endpoint,
+   * such as get, post, put, delete, etc.
+   */
+  method: string
+  /**
+   * The HTTP verb of the API endpoint,
+   * such as Get, Create, Update, Delete, etc.
+   */
+  verb: string
+  /**
+   * The entity name of the API endpoint,
+   * such as User, Comment, Post, etc.
+   */
+  entity: string
+  /**
+   * The type name of the API endpoint,
+   * such as ApiGetUsers, ApiCreatePost, ApiUpdateComment, etc.
+   */
+  type: string
+  /**
+   * The value of the type of the API endpoint,
+   * such as paths['/users']['get'], paths['/posts']['post'], paths['/comments']['put'], etc.
+   */
+  typeValue: string
+  /**
+   * The type name of the query parameters of the API endpoint,
+   * such as ApiGetUsersQuery, ApiCreatePostQuery, ApiUpdateCommentQuery, etc.
+   */
+  typeQuery: string
+  /**
+   * The value of the type of the query parameters of the API endpoint,
+   * such as ApiGetUsersQuery['parameters']['query'], ApiCreatePostQuery['parameters']['query'],
+   * ApiUpdateCommentQuery['parameters']['query'], etc.
+   */
+  typeQueryValue: string
+  /**
+   * The type name of the request body of the API endpoint,
+   * such as ApiGetUsersRequestBody, ApiCreatePostRequestBody, ApiUpdateCommentRequestBody, etc.
+   */
+  typeRequestBody: string
+  /**
+   * The value of the type of the request body of the API endpoint,
+   * such as ApiGetUsersRequestBody['requestBody']['content']['application/json'],
+   * ApiCreatePostRequestBody['requestBody']['content']['application/json'],
+   * ApiUpdateCommentRequestBody['requestBody']['content']['application/json'], etc.
+   */
+  typeRequestBodyValue: string
+  /**
+   * The type name of the response body of the API endpoint,
+   * such as ApiGetUsersResponseBody, ApiCreatePostResponseBody, ApiUpdateCommentResponseBody, etc.
+   */
+  typeResponseBody: string
+  /**
+   * The value of the type of the response body of the API endpoint,
+   * such as ApiGetUsersResponseBody['responses']['200']['content']['application/json'],
+   * ApiCreatePostResponseBody['responses']['201']['content']['application/json'],
+   * ApiUpdateCommentResponseBody['responses']['200']['content']['application/json'], etc.
+   */
+  typeResponseBodyValue: string
+}
+```

package/dist/{chunk-JWKB7AQQ.js → chunk-6T5EWOBD.js}

@@ -22736,10 +22736,10 @@ async function getConfig() {
 // src/transformer.ts
 import pluralize from "pluralize";
 import { camelize, pascalCase } from "rattail";
-function transformModuleName(name) {
+function transformModuleName({ name }) {
   return camelize(name);
 }
-function transformVerb(method) {
+function transformVerb({ method }) {
   switch (method) {
     case "post":
       return "Create";
@@ -22749,10 +22749,10 @@ function transformVerb(method) {
       return pascalCase(method);
   }
 }
-function transformUrl(path13, base) {
+function transformUrl({ path: path13, base }) {
   return (base ? path13.replace(base, "") : path13).replace(/{/g, ":").replace(/}/g, "");
 }
-function transformEntity(path13, method, base) {
+function transformEntity({ path: path13, method, base }) {
   path13 = base ? path13.replace(base, "") : path13;
   const words = path13.split("/").filter(Boolean);
   return words.reduce((entity, word, index) => {
@@ -22766,31 +22766,35 @@ function transformEntity(path13, method, base) {
     return `${entity}${word}`;
   }, "");
 }
-function transformFn(verb, entity) {
+function transformFn({ verb, entity }) {
   return `api${verb}${entity}`;
 }
-function transformType(verb, entity) {
+function transformType({ verb, entity }) {
   return `Api${verb}${entity}`;
 }
-function transformTypeValue(path13, method) {
+function transformTypeValue({ path: path13, method }) {
   return `paths['${path13}']['${method}']`;
 }
-function transformTypeQuery(verb, entity) {
+function transformTypeQuery({ verb, entity }) {
   return `Api${verb}${entity}Query`;
 }
-function transformTypeQueryValue(type2) {
+function transformTypeQueryValue({ type: type2 }) {
   return `${type2}['parameters']['query']`;
 }
-function transformTypeRequestBody(verb, entity) {
+function transformTypeRequestBody({ verb, entity }) {
   return `Api${verb}${entity}RequestBody`;
 }
-function transformTypeRequestBodyValue(type2) {
+function transformTypeRequestBodyValue({ type: type2 }) {
   return `${type2}['requestBody']['content']['application/json']`;
 }
-function transformTypeResponseBody(verb, entity) {
+function transformTypeResponseBody({ verb, entity }) {
   return `Api${verb}${entity}ResponseBody`;
 }
-function transformTypeResponseBodyValue(type2, statusCode, mime) {
+function transformTypeResponseBodyValue({
+  type: type2,
+  statusCode,
+  mime
+}) {
   return `${type2}['responses']['${statusCode}']['content']['${mime}']`;
 }
 function createTransformer() {
@@ -22822,23 +22826,22 @@ function partitionApiModules(schema2, transformer, options8) {
       path13 = base ? base + path13 : path13;
       const pathItems = schemaPaths[path13];
       const childPayloads = Object.entries(pathItems).reduce((payloads3, [method, operation]) => {
-        const url2 = transformer.url(path13, base);
-        const entity = transformer.entity(path13, method, base);
-        const verb = transformer.verb(method);
-        const fn = transformer.fn(verb, entity);
-        const type2 = transformer.type(verb, entity);
-        const typeValue = transformer.typeValue(path13, method);
-        const typeQuery = transformer.typeQuery(verb, entity);
-        const typeQueryValue = hasQueryParameter(operation) ? transformer.typeQueryValue(type2) : "never";
-        const typeRequestBody = transformer.typeRequestBody(verb, entity);
-        const typeRequestBodyValue = operation.requestBody ? transformer.typeRequestBodyValue(type2) : "never";
-        const typeResponseBody = transformer.typeResponseBody(verb, entity);
+        const url2 = transformer.url({ path: path13, base });
+        const entity = transformer.entity({ path: path13, method, base });
+        const verb = transformer.verb({ method });
+        const fn = transformer.fn({ verb, entity });
+        const type2 = transformer.type({ verb, entity });
+        const typeValue = transformer.typeValue({ path: path13, method });
+        const typeQuery = transformer.typeQuery({ verb, entity });
+        const typeQueryValue = hasQueryParameter(operation) ? transformer.typeQueryValue({ type: type2 }) : "never";
+        const typeRequestBody = transformer.typeRequestBody({ verb, entity });
+        const typeRequestBodyValue = operation.requestBody ? transformer.typeRequestBodyValue({ type: type2 }) : "never";
+        const typeResponseBody = transformer.typeResponseBody({ verb, entity });
         const statusCode = statusCodes[method] ?? 200;
-        const mime = (operation.responses?.[statusCode]).content?.["application/json"] ? "application/json" : "*/*";
-        const typeResponseBodyValue = hasResponseBody(operation) ? transformer.typeResponseBodyValue(type2, statusCode, mime) : "never";
+        const mime = operation.responses?.[statusCode]?.content?.["application/json"] ? "application/json" : "*/*";
+        const typeResponseBodyValue = hasResponseBody(operation) ? transformer.typeResponseBodyValue({ type: type2, statusCode, mime }) : "never";
         payloads3.push({
           fn,
-          path: path13,
           url: url2,
           method,
           verb,
@@ -22857,13 +22860,13 @@ function partitionApiModules(schema2, transformer, options8) {
       payloads2.push(...childPayloads);
       return payloads2;
     }, []);
-    apiModules2.push({ name: transformer.moduleName(name), payloads });
+    apiModules2.push({ name: transformer.moduleName({ name }), payloads });
     return apiModules2;
   }, []);
   return apiModules;
 }
 function renderApiModules(apiModules, options8) {
-  const { output, ts, override, preset } = options8;
+  const { output, ts, overrides, preset } = options8;
   const templateFile = readTemplateFile(preset);
   const typesFilename = options8.typesFilename.replace(".ts", "");
   return Promise.all(
@@ -22881,7 +22884,8 @@ function renderApiModules(apiModules, options8) {
           printWidth: 120
         }).then((content) => {
           const path13 = resolve3(output, `${apiModule.name}.${ts ? "ts" : "js"}`);
-          if ((!override || isArray(override) && !override.includes(apiModule.name)) && fse.existsSync(path13)) {
+          const shouldSkip = (!overrides || isArray(overrides) && !overrides.includes(apiModule.name)) && fse.existsSync(path13);
+          if (shouldSkip) {
             logger.warn(`File already exists, skip: ${path13}`);
             promiseResolve(content);
             return;
@@ -22907,7 +22911,7 @@ async function generate(userOptions = {}) {
   const {
     base,
     ts = true,
-    override = true,
+    overrides = true,
     preset = "axle",
     statusCodeStrategy = "strict",
     input = "./schema.json",
@@ -22926,7 +22930,7 @@ async function generate(userOptions = {}) {
     await generateTypes(schema2, output, typesFilename);
   }
   const apiModules = partitionApiModules(schema2, mergedTransformer, { statusCodes, ts, base });
-  await renderApiModules(apiModules, { output, typesFilename, ts, override, preset });
+  await renderApiModules(apiModules, { output, typesFilename, ts, overrides, preset });
   logger.success("Done");
 }
 

package/dist/cli.cjs

@@ -101995,10 +101995,10 @@ var init_config = __esm({
 });
 
 // src/transformer.ts
-function transformModuleName(name) {
+function transformModuleName({ name }) {
   return (0, import_rattail.camelize)(name);
 }
-function transformVerb(method) {
+function transformVerb({ method }) {
   switch (method) {
     case "post":
       return "Create";
@@ -102008,10 +102008,10 @@ function transformVerb(method) {
       return (0, import_rattail.pascalCase)(method);
   }
 }
-function transformUrl(path13, base) {
+function transformUrl({ path: path13, base }) {
   return (base ? path13.replace(base, "") : path13).replace(/{/g, ":").replace(/}/g, "");
 }
-function transformEntity(path13, method, base) {
+function transformEntity({ path: path13, method, base }) {
   path13 = base ? path13.replace(base, "") : path13;
   const words = path13.split("/").filter(Boolean);
   return words.reduce((entity, word, index) => {
@@ -102025,31 +102025,35 @@ function transformEntity(path13, method, base) {
     return `${entity}${word}`;
   }, "");
 }
-function transformFn(verb, entity) {
+function transformFn({ verb, entity }) {
   return `api${verb}${entity}`;
 }
-function transformType(verb, entity) {
+function transformType({ verb, entity }) {
   return `Api${verb}${entity}`;
 }
-function transformTypeValue(path13, method) {
+function transformTypeValue({ path: path13, method }) {
   return `paths['${path13}']['${method}']`;
 }
-function transformTypeQuery(verb, entity) {
+function transformTypeQuery({ verb, entity }) {
   return `Api${verb}${entity}Query`;
 }
-function transformTypeQueryValue(type2) {
+function transformTypeQueryValue({ type: type2 }) {
   return `${type2}['parameters']['query']`;
 }
-function transformTypeRequestBody(verb, entity) {
+function transformTypeRequestBody({ verb, entity }) {
   return `Api${verb}${entity}RequestBody`;
 }
-function transformTypeRequestBodyValue(type2) {
+function transformTypeRequestBodyValue({ type: type2 }) {
   return `${type2}['requestBody']['content']['application/json']`;
 }
-function transformTypeResponseBody(verb, entity) {
+function transformTypeResponseBody({ verb, entity }) {
   return `Api${verb}${entity}ResponseBody`;
 }
-function transformTypeResponseBodyValue(type2, statusCode, mime) {
+function transformTypeResponseBodyValue({
+  type: type2,
+  statusCode,
+  mime
+}) {
   return `${type2}['responses']['${statusCode}']['content']['${mime}']`;
 }
 function createTransformer() {
@@ -102097,23 +102101,22 @@ function partitionApiModules(schema2, transformer, options8) {
       path13 = base ? base + path13 : path13;
       const pathItems = schemaPaths[path13];
       const childPayloads = Object.entries(pathItems).reduce((payloads3, [method, operation]) => {
-        const url2 = transformer.url(path13, base);
-        const entity = transformer.entity(path13, method, base);
-        const verb = transformer.verb(method);
-        const fn8 = transformer.fn(verb, entity);
-        const type2 = transformer.type(verb, entity);
-        const typeValue = transformer.typeValue(path13, method);
-        const typeQuery = transformer.typeQuery(verb, entity);
-        const typeQueryValue = hasQueryParameter(operation) ? transformer.typeQueryValue(type2) : "never";
-        const typeRequestBody = transformer.typeRequestBody(verb, entity);
-        const typeRequestBodyValue = operation.requestBody ? transformer.typeRequestBodyValue(type2) : "never";
-        const typeResponseBody = transformer.typeResponseBody(verb, entity);
+        const url2 = transformer.url({ path: path13, base });
+        const entity = transformer.entity({ path: path13, method, base });
+        const verb = transformer.verb({ method });
+        const fn8 = transformer.fn({ verb, entity });
+        const type2 = transformer.type({ verb, entity });
+        const typeValue = transformer.typeValue({ path: path13, method });
+        const typeQuery = transformer.typeQuery({ verb, entity });
+        const typeQueryValue = hasQueryParameter(operation) ? transformer.typeQueryValue({ type: type2 }) : "never";
+        const typeRequestBody = transformer.typeRequestBody({ verb, entity });
+        const typeRequestBodyValue = operation.requestBody ? transformer.typeRequestBodyValue({ type: type2 }) : "never";
+        const typeResponseBody = transformer.typeResponseBody({ verb, entity });
         const statusCode = statusCodes[method] ?? 200;
-        const mime = (operation.responses?.[statusCode]).content?.["application/json"] ? "application/json" : "*/*";
-        const typeResponseBodyValue = hasResponseBody(operation) ? transformer.typeResponseBodyValue(type2, statusCode, mime) : "never";
+        const mime = operation.responses?.[statusCode]?.content?.["application/json"] ? "application/json" : "*/*";
+        const typeResponseBodyValue = hasResponseBody(operation) ? transformer.typeResponseBodyValue({ type: type2, statusCode, mime }) : "never";
         payloads3.push({
           fn: fn8,
-          path: path13,
           url: url2,
           method,
           verb,
@@ -102132,13 +102135,13 @@ function partitionApiModules(schema2, transformer, options8) {
       payloads2.push(...childPayloads);
       return payloads2;
     }, []);
-    apiModules2.push({ name: transformer.moduleName(name), payloads });
+    apiModules2.push({ name: transformer.moduleName({ name }), payloads });
     return apiModules2;
   }, []);
   return apiModules;
 }
 function renderApiModules(apiModules, options8) {
-  const { output, ts: ts9, override, preset } = options8;
+  const { output, ts: ts9, overrides, preset } = options8;
   const templateFile = readTemplateFile(preset);
   const typesFilename = options8.typesFilename.replace(".ts", "");
   return Promise.all(
@@ -102156,7 +102159,8 @@ function renderApiModules(apiModules, options8) {
           printWidth: 120
         }).then((content) => {
           const path13 = (0, import_path14.resolve)(output, `${apiModule.name}.${ts9 ? "ts" : "js"}`);
-          if ((!override || (0, import_rattail2.isArray)(override) && !override.includes(apiModule.name)) && import_fs_extra2.default.existsSync(path13)) {
+          const shouldSkip = (!overrides || (0, import_rattail2.isArray)(overrides) && !overrides.includes(apiModule.name)) && import_fs_extra2.default.existsSync(path13);
+          if (shouldSkip) {
             import_rslog.logger.warn(`File already exists, skip: ${path13}`);
             promiseResolve(content);
             return;
@@ -102182,7 +102186,7 @@ async function generate(userOptions = {}) {
   const {
     base,
     ts: ts9 = true,
-    override = true,
+    overrides = true,
     preset = "axle",
     statusCodeStrategy = "strict",
     input = "./schema.json",
@@ -102201,7 +102205,7 @@ async function generate(userOptions = {}) {
     await generateTypes(schema2, output, typesFilename);
   }
   const apiModules = partitionApiModules(schema2, mergedTransformer, { statusCodes, ts: ts9, base });
-  await renderApiModules(apiModules, { output, typesFilename, ts: ts9, override, preset });
+  await renderApiModules(apiModules, { output, typesFilename, ts: ts9, overrides, preset });
   import_rslog.logger.success("Done");
 }
 var import_path14, import_ejs, import_fs_extra2, import_openapi_typescript, import_rattail2, import_rslog;

package/dist/cli.js

@@ -9,7 +9,7 @@ import { Command } from "commander";
 var program = new Command();
 program.version(getCliVersion());
 program.action(async () => {
-  const { generate } = await import("./generate-LOGO7XCM.js");
+  const { generate } = await import("./generate-544AKFJX.js");
   return generate();
 });
 program.parse();

package/dist/{generate-LOGO7XCM.js → generate-544AKFJX.js}

@@ -3,7 +3,7 @@ import {
   generateTypes,
   partitionApiModules,
   renderApiModules
-} from "./chunk-JWKB7AQQ.js";
+} from "./chunk-6T5EWOBD.js";
 import "./chunk-6N4OHGAC.js";
 import "./chunk-6OIOYGN7.js";
 export {

package/dist/index.cjs

@@ -79260,10 +79260,10 @@ init_cjs_shims();
 init_cjs_shims();
 var import_pluralize = __toESM(require("pluralize"), 1);
 var import_rattail = require("rattail");
-function transformModuleName(name) {
+function transformModuleName({ name }) {
   return (0, import_rattail.camelize)(name);
 }
-function transformVerb(method) {
+function transformVerb({ method }) {
   switch (method) {
     case "post":
       return "Create";
@@ -79273,10 +79273,10 @@ function transformVerb(method) {
       return (0, import_rattail.pascalCase)(method);
   }
 }
-function transformUrl(path13, base) {
+function transformUrl({ path: path13, base }) {
   return (base ? path13.replace(base, "") : path13).replace(/{/g, ":").replace(/}/g, "");
 }
-function transformEntity(path13, method, base) {
+function transformEntity({ path: path13, method, base }) {
   path13 = base ? path13.replace(base, "") : path13;
   const words = path13.split("/").filter(Boolean);
   return words.reduce((entity, word, index) => {
@@ -79290,31 +79290,35 @@ function transformEntity(path13, method, base) {
     return `${entity}${word}`;
   }, "");
 }
-function transformFn(verb, entity) {
+function transformFn({ verb, entity }) {
   return `api${verb}${entity}`;
 }
-function transformType(verb, entity) {
+function transformType({ verb, entity }) {
   return `Api${verb}${entity}`;
 }
-function transformTypeValue(path13, method) {
+function transformTypeValue({ path: path13, method }) {
   return `paths['${path13}']['${method}']`;
 }
-function transformTypeQuery(verb, entity) {
+function transformTypeQuery({ verb, entity }) {
   return `Api${verb}${entity}Query`;
 }
-function transformTypeQueryValue(type2) {
+function transformTypeQueryValue({ type: type2 }) {
   return `${type2}['parameters']['query']`;
 }
-function transformTypeRequestBody(verb, entity) {
+function transformTypeRequestBody({ verb, entity }) {
   return `Api${verb}${entity}RequestBody`;
 }
-function transformTypeRequestBodyValue(type2) {
+function transformTypeRequestBodyValue({ type: type2 }) {
   return `${type2}['requestBody']['content']['application/json']`;
 }
-function transformTypeResponseBody(verb, entity) {
+function transformTypeResponseBody({ verb, entity }) {
   return `Api${verb}${entity}ResponseBody`;
 }
-function transformTypeResponseBodyValue(type2, statusCode, mime) {
+function transformTypeResponseBodyValue({
+  type: type2,
+  statusCode,
+  mime
+}) {
   return `${type2}['responses']['${statusCode}']['content']['${mime}']`;
 }
 function createTransformer() {
@@ -102134,23 +102138,22 @@ function partitionApiModules(schema2, transformer, options8) {
       path13 = base ? base + path13 : path13;
       const pathItems = schemaPaths[path13];
       const childPayloads = Object.entries(pathItems).reduce((payloads3, [method, operation]) => {
-        const url2 = transformer.url(path13, base);
-        const entity = transformer.entity(path13, method, base);
-        const verb = transformer.verb(method);
-        const fn8 = transformer.fn(verb, entity);
-        const type2 = transformer.type(verb, entity);
-        const typeValue = transformer.typeValue(path13, method);
-        const typeQuery = transformer.typeQuery(verb, entity);
-        const typeQueryValue = hasQueryParameter(operation) ? transformer.typeQueryValue(type2) : "never";
-        const typeRequestBody = transformer.typeRequestBody(verb, entity);
-        const typeRequestBodyValue = operation.requestBody ? transformer.typeRequestBodyValue(type2) : "never";
-        const typeResponseBody = transformer.typeResponseBody(verb, entity);
+        const url2 = transformer.url({ path: path13, base });
+        const entity = transformer.entity({ path: path13, method, base });
+        const verb = transformer.verb({ method });
+        const fn8 = transformer.fn({ verb, entity });
+        const type2 = transformer.type({ verb, entity });
+        const typeValue = transformer.typeValue({ path: path13, method });
+        const typeQuery = transformer.typeQuery({ verb, entity });
+        const typeQueryValue = hasQueryParameter(operation) ? transformer.typeQueryValue({ type: type2 }) : "never";
+        const typeRequestBody = transformer.typeRequestBody({ verb, entity });
+        const typeRequestBodyValue = operation.requestBody ? transformer.typeRequestBodyValue({ type: type2 }) : "never";
+        const typeResponseBody = transformer.typeResponseBody({ verb, entity });
         const statusCode = statusCodes[method] ?? 200;
-        const mime = (operation.responses?.[statusCode]).content?.["application/json"] ? "application/json" : "*/*";
-        const typeResponseBodyValue = hasResponseBody(operation) ? transformer.typeResponseBodyValue(type2, statusCode, mime) : "never";
+        const mime = operation.responses?.[statusCode]?.content?.["application/json"] ? "application/json" : "*/*";
+        const typeResponseBodyValue = hasResponseBody(operation) ? transformer.typeResponseBodyValue({ type: type2, statusCode, mime }) : "never";
         payloads3.push({
           fn: fn8,
-          path: path13,
           url: url2,
           method,
           verb,
@@ -102169,13 +102172,13 @@ function partitionApiModules(schema2, transformer, options8) {
       payloads2.push(...childPayloads);
       return payloads2;
     }, []);
-    apiModules2.push({ name: transformer.moduleName(name), payloads });
+    apiModules2.push({ name: transformer.moduleName({ name }), payloads });
     return apiModules2;
   }, []);
   return apiModules;
 }
 function renderApiModules(apiModules, options8) {
-  const { output, ts: ts9, override, preset } = options8;
+  const { output, ts: ts9, overrides, preset } = options8;
   const templateFile = readTemplateFile(preset);
   const typesFilename = options8.typesFilename.replace(".ts", "");
   return Promise.all(
@@ -102193,7 +102196,8 @@ function renderApiModules(apiModules, options8) {
           printWidth: 120
         }).then((content) => {
           const path13 = (0, import_path14.resolve)(output, `${apiModule.name}.${ts9 ? "ts" : "js"}`);
-          if ((!override || (0, import_rattail2.isArray)(override) && !override.includes(apiModule.name)) && import_fs_extra2.default.existsSync(path13)) {
+          const shouldSkip = (!overrides || (0, import_rattail2.isArray)(overrides) && !overrides.includes(apiModule.name)) && import_fs_extra2.default.existsSync(path13);
+          if (shouldSkip) {
             import_rslog.logger.warn(`File already exists, skip: ${path13}`);
             promiseResolve(content);
             return;
@@ -102219,7 +102223,7 @@ async function generate(userOptions = {}) {
   const {
     base,
     ts: ts9 = true,
-    override = true,
+    overrides = true,
     preset = "axle",
     statusCodeStrategy = "strict",
     input = "./schema.json",
@@ -102238,7 +102242,7 @@ async function generate(userOptions = {}) {
     await generateTypes(schema2, output, typesFilename);
   }
   const apiModules = partitionApiModules(schema2, mergedTransformer, { statusCodes, ts: ts9, base });
-  await renderApiModules(apiModules, { output, typesFilename, ts: ts9, override, preset });
+  await renderApiModules(apiModules, { output, typesFilename, ts: ts9, overrides, preset });
   import_rslog.logger.success("Done");
 }
 

package/dist/index.d.cts

@@ -1,19 +1,56 @@
 import { OpenAPI3, OperationObject } from 'openapi-typescript';
 export { default as pluralize } from 'pluralize';
 
-declare function transformModuleName(name: string): string;
-declare function transformVerb(method: string): string;
-declare function transformUrl(path: string, base?: string): string;
-declare function transformEntity(path: string, method: string, base?: string): string;
-declare function transformFn(verb: string, entity: string): string;
-declare function transformType(verb: string, entity: string): string;
-declare function transformTypeValue(path: string, method: string): string;
-declare function transformTypeQuery(verb: string, entity: string): string;
-declare function transformTypeQueryValue(type: string): string;
-declare function transformTypeRequestBody(verb: string, entity: string): string;
-declare function transformTypeRequestBodyValue(type: string): string;
-declare function transformTypeResponseBody(verb: string, entity: string): string;
-declare function transformTypeResponseBodyValue(type: string, statusCode: number, mime: string): string;
+declare function transformModuleName({ name }: {
+    name: string;
+}): string;
+declare function transformVerb({ method }: {
+    method: string;
+}): string;
+declare function transformUrl({ path, base }: {
+    path: string;
+    base?: string;
+}): string;
+declare function transformEntity({ path, method, base }: {
+    path: string;
+    method: string;
+    base?: string;
+}): string;
+declare function transformFn({ verb, entity }: {
+    verb: string;
+    entity: string;
+}): string;
+declare function transformType({ verb, entity }: {
+    verb: string;
+    entity: string;
+}): string;
+declare function transformTypeValue({ path, method }: {
+    path: string;
+    method: string;
+}): string;
+declare function transformTypeQuery({ verb, entity }: {
+    verb: string;
+    entity: string;
+}): string;
+declare function transformTypeQueryValue({ type }: {
+    type: string;
+}): string;
+declare function transformTypeRequestBody({ verb, entity }: {
+    verb: string;
+    entity: string;
+}): string;
+declare function transformTypeRequestBodyValue({ type }: {
+    type: string;
+}): string;
+declare function transformTypeResponseBody({ verb, entity }: {
+    verb: string;
+    entity: string;
+}): string;
+declare function transformTypeResponseBodyValue({ type, statusCode, mime, }: {
+    type: string;
+    statusCode: number;
+    mime: string;
+}): string;
 interface Transformer {
     moduleName: typeof transformModuleName;
     verb: typeof transformVerb;
@@ -65,41 +102,124 @@ declare function hasQueryParameter(operation: OperationObject): boolean;
 declare function hasResponseBody(operation: OperationObject): boolean;
 declare function getCliVersion(): any;
 
+interface ApiModuleTemplateData {
+    /**
+     * API module metadata
+     */
+    apiModule: ApiModule;
+    /**
+     * The name of the generated api ts type aggregation file
+     */
+    typesFilename: string;
+    /**
+     * Whether to generate ts code
+     */
+    ts: boolean;
+}
+interface ApiModule {
+    /**
+     * The name of the API module
+     */
+    name: string;
+    /**
+     * API module payloads
+     */
+    payloads: ApiModulePayload[];
+}
 interface ApiModulePayload {
+    /**
+     * The name of the API function/dispatcher, such as apiGetUsers, apiCreatePost, apiUpdateComment, etc.
+     */
     fn: string;
-    path: string;
+    /**
+     * The URL of the API endpoint, such as /users, /posts, /comments, etc.
+     */
     url: string;
+    /**
+     * The HTTP method of the API endpoint, such as get, post, put, delete, etc.
+     */
     method: string;
+    /**
+     * The HTTP verb of the API endpoint, such as Get, Create, Update, Delete, etc.
+     */
     verb: string;
+    /**
+     * The entity name of the API endpoint, such as User, Comment, Post, etc.
+     */
     entity: string;
+    /**
+     * The type name of the API endpoint, such as ApiGetUsers, ApiCreatePost, ApiUpdateComment, etc.
+     */
     type: string;
+    /**
+     * The value of the type of the API endpoint, such as paths['/users']['get'], paths['/posts']['post'], paths['/comments']['put'], etc.
+     */
     typeValue: string;
+    /**
+     * The type name of the query parameters of the API endpoint, such as ApiGetUsersQuery, ApiCreatePostQuery, ApiUpdateCommentQuery, etc.
+     */
     typeQuery: string;
+    /**
+     * The value of the type of the query parameters of the API endpoint, such as ApiGetUsersQuery['parameters']['query'], ApiCreatePostQuery['parameters']['query'], ApiUpdateCommentQuery['parameters']['query'], etc.
+     */
     typeQueryValue: string;
+    /**
+     * The type name of the request body of the API endpoint, such as ApiGetUsersRequestBody, ApiCreatePostRequestBody, ApiUpdateCommentRequestBody, etc.
+     */
     typeRequestBody: string;
+    /**
+     * The value of the type of the request body of the API endpoint, such as ApiGetUsersRequestBody['requestBody']['content']['application/json'], ApiCreatePostRequestBody['requestBody']['content']['application/json'], ApiUpdateCommentRequestBody['requestBody']['content']['application/json'], etc.
+     */
     typeRequestBodyValue: string;
+    /**
+     * The type name of the response body of the API endpoint, such as ApiGetUsersResponseBody, ApiCreatePostResponseBody, ApiUpdateCommentResponseBody, etc.
+     */
     typeResponseBody: string;
+    /**
+     * The value of the type of the response body of the API endpoint, such as ApiGetUsersResponseBody['responses']['200']['content']['application/json'], ApiCreatePostResponseBody['responses']['201']['content']['application/json'], ApiUpdateCommentResponseBody['responses']['200']['content']['application/json'], etc.
+     */
     typeResponseBodyValue: string;
 }
-interface ApiModule {
-    name: string;
-    payloads: ApiModulePayload[];
-}
-interface ApiModuleTemplateData {
-    apiModule: ApiModule;
-    typesFilename: string;
-    ts: boolean;
-}
 interface GenerateOptions {
+    /**
+     * The path to the OpenAPI/Swagger schema file.
+     */
     input?: string;
+    /**
+     * The path to the output directory.
+     */
     output?: string;
+    /**
+     * The base path of the API endpoints.
+     */
     base?: string;
+    /**
+     * The filename of the generated openapi types file.
+     */
     typesFilename?: string;
+    /**
+     * The transformer api options, used to override the default transformation rules.
+     */
     transformer?: Partial<Transformer>;
+    /**
+     * Whether to generate TypeScript code.
+     */
     ts?: boolean;
-    override?: boolean | string[];
+    /**
+     * Whether to override the existing files, or an array of filenames to override.
+     */
+    overrides?: boolean | string[];
+    /**
+     * The preset ejs template to use.
+     */
     preset?: Preset;
+    /**
+     * The status code strategy to use. loose: all success status codes are 200, strict: use the openapi recommended success status codes.
+     */
     statusCodeStrategy?: StatusCodeStrategy;
+    /**
+     * The status codes to override the default status codes.
+     */
     statusCodes?: {
         get?: number;
         post?: number;
@@ -119,7 +239,7 @@ declare function renderApiModules(apiModules: ApiModule[], options: {
     output: string;
     typesFilename: string;
     ts: boolean;
-    override: boolean | string[];
+    overrides: boolean | string[];
     preset: Preset;
 }): Promise<unknown[]>;
 declare function generateTypes(schema: OpenAPI3, output: string, typesFilename: string): Promise<void>;

package/dist/index.d.ts

@@ -1,19 +1,56 @@
 import { OpenAPI3, OperationObject } from 'openapi-typescript';
 export { default as pluralize } from 'pluralize';
 
-declare function transformModuleName(name: string): string;
-declare function transformVerb(method: string): string;
-declare function transformUrl(path: string, base?: string): string;
-declare function transformEntity(path: string, method: string, base?: string): string;
-declare function transformFn(verb: string, entity: string): string;
-declare function transformType(verb: string, entity: string): string;
-declare function transformTypeValue(path: string, method: string): string;
-declare function transformTypeQuery(verb: string, entity: string): string;
-declare function transformTypeQueryValue(type: string): string;
-declare function transformTypeRequestBody(verb: string, entity: string): string;
-declare function transformTypeRequestBodyValue(type: string): string;
-declare function transformTypeResponseBody(verb: string, entity: string): string;
-declare function transformTypeResponseBodyValue(type: string, statusCode: number, mime: string): string;
+declare function transformModuleName({ name }: {
+    name: string;
+}): string;
+declare function transformVerb({ method }: {
+    method: string;
+}): string;
+declare function transformUrl({ path, base }: {
+    path: string;
+    base?: string;
+}): string;
+declare function transformEntity({ path, method, base }: {
+    path: string;
+    method: string;
+    base?: string;
+}): string;
+declare function transformFn({ verb, entity }: {
+    verb: string;
+    entity: string;
+}): string;
+declare function transformType({ verb, entity }: {
+    verb: string;
+    entity: string;
+}): string;
+declare function transformTypeValue({ path, method }: {
+    path: string;
+    method: string;
+}): string;
+declare function transformTypeQuery({ verb, entity }: {
+    verb: string;
+    entity: string;
+}): string;
+declare function transformTypeQueryValue({ type }: {
+    type: string;
+}): string;
+declare function transformTypeRequestBody({ verb, entity }: {
+    verb: string;
+    entity: string;
+}): string;
+declare function transformTypeRequestBodyValue({ type }: {
+    type: string;
+}): string;
+declare function transformTypeResponseBody({ verb, entity }: {
+    verb: string;
+    entity: string;
+}): string;
+declare function transformTypeResponseBodyValue({ type, statusCode, mime, }: {
+    type: string;
+    statusCode: number;
+    mime: string;
+}): string;
 interface Transformer {
     moduleName: typeof transformModuleName;
     verb: typeof transformVerb;
@@ -65,41 +102,124 @@ declare function hasQueryParameter(operation: OperationObject): boolean;
 declare function hasResponseBody(operation: OperationObject): boolean;
 declare function getCliVersion(): any;
 
+interface ApiModuleTemplateData {
+    /**
+     * API module metadata
+     */
+    apiModule: ApiModule;
+    /**
+     * The name of the generated api ts type aggregation file
+     */
+    typesFilename: string;
+    /**
+     * Whether to generate ts code
+     */
+    ts: boolean;
+}
+interface ApiModule {
+    /**
+     * The name of the API module
+     */
+    name: string;
+    /**
+     * API module payloads
+     */
+    payloads: ApiModulePayload[];
+}
 interface ApiModulePayload {
+    /**
+     * The name of the API function/dispatcher, such as apiGetUsers, apiCreatePost, apiUpdateComment, etc.
+     */
     fn: string;
-    path: string;
+    /**
+     * The URL of the API endpoint, such as /users, /posts, /comments, etc.
+     */
     url: string;
+    /**
+     * The HTTP method of the API endpoint, such as get, post, put, delete, etc.
+     */
     method: string;
+    /**
+     * The HTTP verb of the API endpoint, such as Get, Create, Update, Delete, etc.
+     */
     verb: string;
+    /**
+     * The entity name of the API endpoint, such as User, Comment, Post, etc.
+     */
     entity: string;
+    /**
+     * The type name of the API endpoint, such as ApiGetUsers, ApiCreatePost, ApiUpdateComment, etc.
+     */
     type: string;
+    /**
+     * The value of the type of the API endpoint, such as paths['/users']['get'], paths['/posts']['post'], paths['/comments']['put'], etc.
+     */
     typeValue: string;
+    /**
+     * The type name of the query parameters of the API endpoint, such as ApiGetUsersQuery, ApiCreatePostQuery, ApiUpdateCommentQuery, etc.
+     */
     typeQuery: string;
+    /**
+     * The value of the type of the query parameters of the API endpoint, such as ApiGetUsersQuery['parameters']['query'], ApiCreatePostQuery['parameters']['query'], ApiUpdateCommentQuery['parameters']['query'], etc.
+     */
     typeQueryValue: string;
+    /**
+     * The type name of the request body of the API endpoint, such as ApiGetUsersRequestBody, ApiCreatePostRequestBody, ApiUpdateCommentRequestBody, etc.
+     */
     typeRequestBody: string;
+    /**
+     * The value of the type of the request body of the API endpoint, such as ApiGetUsersRequestBody['requestBody']['content']['application/json'], ApiCreatePostRequestBody['requestBody']['content']['application/json'], ApiUpdateCommentRequestBody['requestBody']['content']['application/json'], etc.
+     */
     typeRequestBodyValue: string;
+    /**
+     * The type name of the response body of the API endpoint, such as ApiGetUsersResponseBody, ApiCreatePostResponseBody, ApiUpdateCommentResponseBody, etc.
+     */
     typeResponseBody: string;
+    /**
+     * The value of the type of the response body of the API endpoint, such as ApiGetUsersResponseBody['responses']['200']['content']['application/json'], ApiCreatePostResponseBody['responses']['201']['content']['application/json'], ApiUpdateCommentResponseBody['responses']['200']['content']['application/json'], etc.
+     */
     typeResponseBodyValue: string;
 }
-interface ApiModule {
-    name: string;
-    payloads: ApiModulePayload[];
-}
-interface ApiModuleTemplateData {
-    apiModule: ApiModule;
-    typesFilename: string;
-    ts: boolean;
-}
 interface GenerateOptions {
+    /**
+     * The path to the OpenAPI/Swagger schema file.
+     */
     input?: string;
+    /**
+     * The path to the output directory.
+     */
     output?: string;
+    /**
+     * The base path of the API endpoints.
+     */
     base?: string;
+    /**
+     * The filename of the generated openapi types file.
+     */
     typesFilename?: string;
+    /**
+     * The transformer api options, used to override the default transformation rules.
+     */
     transformer?: Partial<Transformer>;
+    /**
+     * Whether to generate TypeScript code.
+     */
     ts?: boolean;
-    override?: boolean | string[];
+    /**
+     * Whether to override the existing files, or an array of filenames to override.
+     */
+    overrides?: boolean | string[];
+    /**
+     * The preset ejs template to use.
+     */
     preset?: Preset;
+    /**
+     * The status code strategy to use. loose: all success status codes are 200, strict: use the openapi recommended success status codes.
+     */
     statusCodeStrategy?: StatusCodeStrategy;
+    /**
+     * The status codes to override the default status codes.
+     */
     statusCodes?: {
         get?: number;
         post?: number;
@@ -119,7 +239,7 @@ declare function renderApiModules(apiModules: ApiModule[], options: {
     output: string;
     typesFilename: string;
     ts: boolean;
-    override: boolean | string[];
+    overrides: boolean | string[];
     preset: Preset;
 }): Promise<unknown[]>;
 declare function generateTypes(schema: OpenAPI3, output: string, typesFilename: string): Promise<void>;

package/dist/index.js

@@ -19,7 +19,7 @@ import {
   transformTypeValue,
   transformUrl,
   transformVerb
-} from "./chunk-JWKB7AQQ.js";
+} from "./chunk-6T5EWOBD.js";
 import {
   createStatusCodesByStrategy,
   getCliVersion,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "api-farmer",
-  "version": "0.0.3",
-  "description": "A cli to generate apis from a schema",
+  "version": "0.0.5",
+  "description": "API module generation tool based on Openapi3/Swagger2.",
   "keywords": [
     "cli",
     "api generator",
@@ -33,7 +33,8 @@
     "af": "dist/cli.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "templates"
   ],
   "simple-git-hooks": {
     "pre-commit": "pnpm exec nano-staged --allow-empty",

package/templates/axios.ejs

@@ -0,0 +1,42 @@
+<% if (ts) { %> import { type AxiosRequestConfig } from 'axios' <% } %>
+import { request } from '@/request'
+<% if (ts) { %> import { type paths } from './<%- typesFilename %>' <% } %>
+
+<% apiModule.payloads.forEach(payload => { %> -%>
+export const <%- payload.fn %> = (config<% if (ts) { %>: AxiosRequestConfig<<%- payload.typeRequestBody %>> <% } %>) 
+=> request<% if (ts) { %><any, Res<<%- payload.typeResponseBody %>>><% } %>({
+  url: '<%- payload.url %>', 
+  method: '<%- payload.method %>',
+  ...config
+})
+
+<% }) %>
+
+<% if (ts) { %>
+<% apiModule.payloads.forEach(payload => { %> -%>
+export type <%- payload.type %> = <%- payload.typeValue %>
+
+<% }) %>
+
+<% apiModule.payloads.forEach(payload => { %> -%>
+  <% if (payload.typeQueryValue) { %>
+  export type <%- payload.typeQuery %> = <%- payload.typeQueryValue %>
+  
+<% } %>
+<% }) %>
+
+<% apiModule.payloads.forEach(payload => { %> -%>
+<% if (payload.typeRequestBodyValue) { %>
+export type <%- payload.typeRequestBody %> = <%- payload.typeRequestBodyValue %>
+
+<% } %>
+<% }) %>
+
+<% apiModule.payloads.forEach(payload => { %> -%>
+<% if (payload.typeResponseBodyValue) { %>
+export type <%- payload.typeResponseBody %> = <%- payload.typeResponseBodyValue %>
+  
+<% } %>
+<% }) %>
+<% } %>
+

package/templates/axle.ejs

@@ -0,0 +1,36 @@
+import { api } from '@/request'
+<% if (ts) { %> import { type paths } from './<%- typesFilename %>' <% } %>
+
+<% apiModule.payloads.forEach(payload => { %> -%>
+export const <%- payload.fn %> = api<% if (ts) { %><Res<<%- payload.typeResponseBody %>>, <%- payload.typeRequestBody %>><% } %>('<%- payload.url %>', '<%- payload.method %>')
+
+<% }) %>
+
+<% if (ts) { %>
+<% apiModule.payloads.forEach(payload => { %> -%>
+export type <%- payload.type %> = <%- payload.typeValue %>
+
+<% }) %>
+
+<% apiModule.payloads.forEach(payload => { %> -%>
+  <% if (payload.typeQueryValue) { %>
+  export type <%- payload.typeQuery %> = <%- payload.typeQueryValue %>
+  
+<% } %>
+<% }) %>
+
+<% apiModule.payloads.forEach(payload => { %> -%>
+<% if (payload.typeRequestBodyValue) { %>
+export type <%- payload.typeRequestBody %> = <%- payload.typeRequestBodyValue %>
+
+<% } %>
+<% }) %>
+
+<% apiModule.payloads.forEach(payload => { %> -%>
+<% if (payload.typeResponseBodyValue) { %>
+export type <%- payload.typeResponseBody %> = <%- payload.typeResponseBodyValue %>
+  
+<% } %>
+<% }) %>
+<% } %>
+