api-farmer 0.0.28 → 0.1.0

package/README.md

@@ -84,6 +84,7 @@ export default defineConfig({
     url() {},
     entity() {},
     fn() {},
+    comment() {},
     type() {},
     typeValue() {},
     typeQuery() {},
@@ -189,6 +190,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-XM2F7GOE.js → chunk-XM4XA35S.js}

@@ -42,6 +42,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 +129,7 @@ function createTransformer() {
     moduleName: transformModuleName,
     verb: transformVerb,
     url: transformUrl,
+    comment: transformComment,
     entity: transformEntity,
     fn: transformFn,
     type: transformType,
@@ -134,6 +151,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 +171,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,
@@ -277,6 +296,7 @@ export {
   getConfig,
   transformModuleName,
   transformUrl,
+  transformComment,
   transformVerb,
   transformEntity,
   transformFn,

package/dist/cli.cjs

@@ -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,

package/dist/cli.js

@@ -8,7 +8,7 @@ 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-BJMNBKQH.js");
   return generate();
 });
 program.parse();

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

@@ -4,7 +4,7 @@ import {
   partitionApiModules,
   renderApiModules,
   transformPayloads
-} from "./chunk-XM2F7GOE.js";
+} from "./chunk-XM4XA35S.js";
 import "./chunk-56NOW5DM.js";
 export {
   generate,

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,
@@ -301,6 +319,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 +339,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,
@@ -462,6 +482,7 @@ var import_pluralize2 = __toESM(require("pluralize"), 1);
   readSchemaContent,
   readTemplateFile,
   renderApiModules,
+  transformComment,
   transformEntity,
   transformFn,
   transformModuleName,

package/dist/index.d.cts

@@ -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.
      */
@@ -304,4 +315,4 @@ 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

@@ -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.
      */
@@ -304,4 +315,4 @@ 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-XM4XA35S.js";
 import {
   createStatusCodesByStrategy,
   findObjectKey,
@@ -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.0",
   "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",
@@ -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) { %>