feat: 更新接口文档实现及示例

pont-config.json

 {
-    "originUrl": "http://localhost:8181/api/v2/api-docs",
+    "originType": "SwaggerV2",
+    "originUrl": "http://127.0.0.1:8081/api/v2/api-docs",
+    "templateType": "fetch",
     "templatePath": "./pont.template",
+    "transformPath": "./pont.transform",
     "outDir": "./src/api/services",
     "surrounding": "typeScript",
     "mocks": {
@@ -9,7 +12,6 @@
         "port": 3101,
         "wrapper": "{\"status\": 200, \"body\": {response}, \"message\": \"OK\"}"
     },
-    "templateType": "fetch",
     "prettierConfig": {
         "printWidth": 120,
         "semi": false,

pont.template.ts

+import * as Pont from 'pont-engine'
 import { Interface, BaseClass, Property, CodeGenerator } from 'pont-engine'
 
 // 接口 API 前缀
 // 通常与项目的 env 配置中的 VITE_GLOB_API_URL_PREFIX 相同
 const API_URL_PREFIX = '/api'
 
+export class FileStructures extends Pont.FileStructures {
+    getModsDeclaration(originCode: string): string {
+        return originCode
+    }
+}
+
 export default class BasicGenerator extends CodeGenerator {
     getParams(inter: Interface, paramsCode: string) {
         let requestParams = inter.getRequestParams(this.surrounding)
 
         const prettier = require('prettier')
         if (prettier.format(paramsCode, { parser: 'typescript' }).includes('{}')) {
-            requestParams = requestParams.replace('params', 'params?')
+            if (!requestParams.includes('form')) {
+                requestParams = requestParams.replace('params', 'params?')
+            }
         }
 
         return `${requestParams.replace(
@@ -54,18 +63,19 @@ export default class BasicGenerator extends CodeGenerator {
         const method = inter.method.toUpperCase()
         const paramsCode = inter.getParamsCode('Params', this.surrounding)
         const requestParams = this.getParams(inter, paramsCode)
+        const undef = inter.response.getInitialValue() === 'undefined'
 
         return `
             /**
              * @desc ${inter.description}
              */
 
-            import * as defs from '../../baseClass';
+            ${undef ? '' : `import * as defs from '../../baseClass';`}
             import { defHttp } from '/@/utils/http/axios'
 
             export ${paramsCode}
 
-            export const init = ${inter.response.getInitialValue()};
+            ${undef ? '' : `export const init = ${inter.response.getInitialValue(true)};`}
 
             export function request(${requestParams}) {
                 return defHttp.request({
@@ -76,6 +86,11 @@ export default class BasicGenerator extends CodeGenerator {
                             ? 'params'
                             : `data: ${requestParams.includes('form') ? 'form || params' : 'params'}`
                     },
+                    ${
+                        requestParams.includes('form')
+                            ? `headers: { 'Content-Type': 'multipart/form-data;charset=UTF-8' },`
+                            : ''
+                    }
 
                     ...config,
                 }, options);

pont.transform.ts

+import { StandardDataSource } from 'pont-engine'
+
+export default function (dataSource: StandardDataSource): StandardDataSource {
+    return dataSource
+}

src/api/services/api.d.ts

@@ -7,8 +7,8 @@ declare namespace defs {
         /** token */
         token?: string
 
-        /** 主键 */
-        userId?: number
+        /** 用户 ID */
+        userId?: string
     }
 
     export class MenuVo {
@@ -59,7 +59,7 @@ declare namespace defs {
         icon?: string
 
         /** 主键 */
-        id?: number
+        id?: string
 
         /** 元数据 */
         meta?: ObjectMap<any, object>
@@ -71,7 +71,7 @@ declare namespace defs {
         path?: string
 
         /** 父级ID */
-        pid?: number
+        pid?: string
 
         /** 序号 */
         serial?: number
@@ -111,7 +111,7 @@ declare namespace defs {
 
     export class RoleVo {
         /** 主键 */
-        id?: number
+        id?: string
 
         /** 名称 */
         name?: string
@@ -140,7 +140,7 @@ declare namespace defs {
         roles?: Array<defs.RoleVo>
 
         /** 主键 */
-        userId?: number
+        userId?: string
 
         /** 用户名 */
         username?: string
@@ -163,7 +163,7 @@ declare namespace defs {
         enabled?: boolean
 
         /** 主键 */
-        id?: number
+        id?: string
 
         /** 最后登录IP地址 */
         lastLoginIp?: string
@@ -185,9 +185,9 @@ declare namespace defs {
     }
 }
 
-declare namespace API {
+namespace API {
     /**
-     *
+     * 身份认证
      */
     export namespace auth {
         /**
@@ -268,12 +268,12 @@ declare namespace API {
     }
 
     /**
-     *
+     * 示例
      */
-    export namespace hello {
+    export namespace example {
         /**
          * hello
-         * /api/hello/
+         * /api/example/
          */
         export namespace hello {
             export class Params {}
@@ -290,8 +290,26 @@ declare namespace API {
         }
 
         /**
+         * download
+         * /api/example/download
+         */
+        export namespace download {
+            export class Params {}
+
+            export type Response = any
+
+            export const init: Response
+
+            export function request(
+                params?: Params,
+                config?: http.RequestConfig<Params>,
+                options?: http.RequestOptions,
+            ): Promise<Response>
+        }
+
+        /**
          * fail
-         * /api/hello/fail
+         * /api/example/fail
          */
         export namespace fail {
             export class Params {}
@@ -309,7 +327,7 @@ declare namespace API {
 
         /**
          * page
-         * /api/hello/page
+         * /api/example/page
          */
         export namespace page {
             export class Params {
@@ -333,15 +351,33 @@ declare namespace API {
                 options?: http.RequestOptions,
             ): Promise<Response>
         }
+
+        /**
+         * 测试 MyBatis Plus 查询
+         * /api/example/test
+         */
+        export namespace test {
+            export class Params {}
+
+            export type Response = string
+
+            export const init: Response
+
+            export function request(
+                params?: Params,
+                config?: http.RequestConfig<Params>,
+                options?: http.RequestOptions,
+            ): Promise<Response>
+        }
     }
 
     /**
-     *
+     * 文件管理
      */
-    export namespace minio {
+    export namespace file {
         /**
          * 文件上传
-         * /api/common/minio/upload
+         * /api/common/file/upload
          */
         export namespace upload {
             export class Params {}
@@ -351,7 +387,7 @@ declare namespace API {
             export const init: Response
 
             export function request(
-                params?: Params,
+                params: Params,
                 form: FormData,
                 config?: http.RequestConfig<Params | FormData>,
                 options?: http.RequestOptions,
@@ -360,7 +396,7 @@ declare namespace API {
     }
 
     /**
-     *
+     * 权限管理
      */
     export namespace permission {
         /**
@@ -384,7 +420,7 @@ declare namespace API {
                 /** 路径 */
                 path?: string
                 /** 父级ID */
-                pid?: number
+                pid?: string
                 /** 重定向 */
                 redirect?: string
                 /** 序号 */
@@ -413,7 +449,7 @@ declare namespace API {
         export namespace deleted {
             export class Params {
                 /** id */
-                id: number
+                id: string
             }
 
             export type Response = string
@@ -434,7 +470,7 @@ declare namespace API {
         export namespace find {
             export class Params {
                 /** id */
-                id: number
+                id: string
             }
 
             export type Response = defs.PermissionVo
@@ -463,7 +499,7 @@ declare namespace API {
                 /** 图标 */
                 icon?: string
                 /** id */
-                id: number
+                id: string
                 /** 元数据 */
                 meta?: string
                 /** 名称 */
@@ -471,7 +507,7 @@ declare namespace API {
                 /** 路径 */
                 path?: string
                 /** 父级ID */
-                pid?: number
+                pid?: string
                 /** 重定向 */
                 redirect?: string
                 /** 序号 */
@@ -526,8 +562,8 @@ declare namespace API {
          */
         export namespace tree {
             export class Params {
-                /** 父级 id */
-                pid?: number
+                /** pid */
+                pid: string
             }
 
             export type Response = Array<defs.PermissionVo>
@@ -543,7 +579,7 @@ declare namespace API {
     }
 
     /**
-     *
+     * 角色管理
      */
     export namespace role {
         /**
@@ -576,7 +612,7 @@ declare namespace API {
         export namespace assign {
             export class Params {
                 /** id */
-                id: number
+                id: string
                 /** ids 多个以逗号分割 */
                 ids: string
             }
@@ -599,7 +635,7 @@ declare namespace API {
         export namespace deleted {
             export class Params {
                 /** id */
-                id: number
+                id: string
             }
 
             export type Response = string
@@ -620,7 +656,7 @@ declare namespace API {
         export namespace find {
             export class Params {
                 /** id */
-                id: number
+                id: string
             }
 
             export type Response = defs.RoleVo
@@ -641,7 +677,7 @@ declare namespace API {
         export namespace modify {
             export class Params {
                 /** id */
-                id: number
+                id: string
                 /** 名称 */
                 name: string
                 /** 标识 */
@@ -706,7 +742,7 @@ declare namespace API {
     }
 
     /**
-     *
+     * 用户管理
      */
     export namespace user {
         /**
@@ -770,7 +806,7 @@ declare namespace API {
         export namespace assign {
             export class Params {
                 /** id */
-                id: number
+                id: string
                 /** ids 多个以逗号分割 */
                 ids: string
             }

src/api/services/baseClass.ts

@@ -2,8 +2,8 @@ export class LoginVo {
     /** token */
     token = ''
 
-    /** 主键 */
-    userId = undefined
+    /** 用户 ID */
+    userId = ''
 }
 
 export class MenuVo {
@@ -54,7 +54,7 @@ export class PermissionVo {
     icon = ''
 
     /** 主键 */
-    id = undefined
+    id = ''
 
     /** 元数据 */
     meta = undefined
@@ -66,7 +66,7 @@ export class PermissionVo {
     path = ''
 
     /** 父级ID */
-    pid = undefined
+    pid = ''
 
     /** 序号 */
     serial = undefined
@@ -106,7 +106,7 @@ export class Result {
 
 export class RoleVo {
     /** 主键 */
-    id = undefined
+    id = ''
 
     /** 名称 */
     name = ''
@@ -135,7 +135,7 @@ export class UserInfo {
     roles = []
 
     /** 主键 */
-    userId = undefined
+    userId = ''
 
     /** 用户名 */
     username = ''
@@ -158,7 +158,7 @@ export class UserVo {
     enabled = false
 
     /** 主键 */
-    id = undefined
+    id = ''
 
     /** 最后登录IP地址 */
     lastLoginIp = ''

src/api/services/mods/auth/index.ts

 /**
- * @description
+ * @description 身份认证
  */
 import * as login from './login'
 import * as logout from './logout'

src/api/services/mods/example/download.ts

+/**
+ * @desc download
+ */
+
+import { defHttp } from '/@/utils/http/axios'
+
+export class Params {}
+
+export function request(params?: Params, config?: http.RequestConfig<Params>, options?: http.RequestOptions) {
+    return defHttp.request(
+        {
+            url: '/example/download',
+            method: 'GET',
+            params,
+
+            ...config,
+        },
+        options,
+    )
+}

src/api/services/mods/hello/fail.ts → src/api/services/mods/example/fail.ts

@@ -12,7 +12,7 @@ export const init = new defs.Result()
 export function request(params?: Params, config?: http.RequestConfig<Params>, options?: http.RequestOptions) {
     return defHttp.request(
         {
-            url: '/hello/fail',
+            url: '/example/fail',
             method: 'GET',
             params,
 

src/api/services/mods/hello/hello.ts → src/api/services/mods/example/hello.ts

@@ -12,7 +12,7 @@ export const init = new defs.Result()
 export function request(params?: Params, config?: http.RequestConfig<Params>, options?: http.RequestOptions) {
     return defHttp.request(
         {
-            url: '/hello/',
+            url: '/example/',
             method: 'GET',
             params,
 

src/api/services/mods/hello/index.ts → src/api/services/mods/example/index.ts

 /**
- * @description
+ * @description 示例
  */
 import * as hello from './hello'
+import * as download from './download'
 import * as fail from './fail'
 import * as page from './page'
+import * as test from './test'
 
-export { hello, fail, page }
+export { hello, download, fail, page, test }

src/api/services/mods/hello/page.ts → src/api/services/mods/example/page.ts

@@ -21,7 +21,7 @@ export const init = new defs.Result()
 export function request(params: Params, config?: http.RequestConfig<Params>, options?: http.RequestOptions) {
     return defHttp.request(
         {
-            url: '/hello/page',
+            url: '/example/page',
             method: 'GET',
             params,
 

src/api/services/mods/example/test.ts

+/**
+ * @desc 测试 MyBatis Plus 查询
+ */
+
+import * as defs from '../../baseClass'
+import { defHttp } from '/@/utils/http/axios'
+
+export class Params {}
+
+export const init = new defs.Result()
+
+export function request(params?: Params, config?: http.RequestConfig<Params>, options?: http.RequestOptions) {
+    return defHttp.request(
+        {
+            url: '/example/test',
+            method: 'GET',
+            params,
+
+            ...config,
+        },
+        options,
+    )
+}

src/api/services/mods/minio/index.ts → src/api/services/mods/file/index.ts

 /**
- * @description
+ * @description 文件管理
  */
 import * as upload from './upload'
 

src/api/services/mods/minio/upload.ts → src/api/services/mods/file/upload.ts

@@ -10,16 +10,17 @@ export class Params {}
 export const init = new defs.Result()
 
 export function request(
-    params?: Params,
+    params: Params,
     form: FormData,
     config?: http.RequestConfig<Params | FormData>,
     options?: http.RequestOptions,
 ) {
     return defHttp.request(
         {
-            url: '/common/minio/upload',
+            url: '/common/file/upload',
             method: 'POST',
             data: form || params,
+            headers: { 'Content-Type': 'multipart/form-data;charset=UTF-8' },
 
             ...config,
         },

src/api/services/mods/index.ts

 import * as auth from './auth'
-import * as hello from './hello'
-import * as minio from './minio'
+import * as example from './example'
+import * as file from './file'
 import * as permission from './permission'
 import * as role from './role'
 import * as user from './user'
 
 export const API = {
     auth,
-    hello,
-    minio,
+    example,
+    file,
     permission,
     role,
     user,

src/api/services/mods/permission/add.ts

@@ -21,7 +21,7 @@ export class Params {
     /** 路径 */
     path?: string
     /** 父级ID */
-    pid?: number
+    pid?: string
     /** 重定向 */
     redirect?: string
     /** 序号 */

src/api/services/mods/permission/deleted.ts

@@ -7,7 +7,7 @@ import { defHttp } from '/@/utils/http/axios'
 
 export class Params {
     /** id */
-    id: number
+    id: string
 }
 
 export const init = new defs.Result()

src/api/services/mods/permission/find.ts

@@ -7,7 +7,7 @@ import { defHttp } from '/@/utils/http/axios'
 
 export class Params {
     /** id */
-    id: number
+    id: string
 }
 
 export const init = new defs.Result()

src/api/services/mods/permission/index.ts

 /**
- * @description
+ * @description 权限管理
  */
 import * as add from './add'
 import * as deleted from './deleted'

src/api/services/mods/permission/modify.ts

@@ -15,7 +15,7 @@ export class Params {
     /** 图标 */
     icon?: string
     /** id */
-    id: number
+    id: string
     /** 元数据 */
     meta?: string
     /** 名称 */
@@ -23,7 +23,7 @@ export class Params {
     /** 路径 */
     path?: string
     /** 父级ID */
-    pid?: number
+    pid?: string
     /** 重定向 */
     redirect?: string
     /** 序号 */

src/api/services/mods/permission/tree.ts

@@ -6,8 +6,8 @@ import * as defs from '../../baseClass'
 import { defHttp } from '/@/utils/http/axios'
 
 export class Params {
-    /** 父级 id */
-    pid?: number
+    /** pid */
+    pid: string
 }
 
 export const init = new defs.Result()

src/api/services/mods/role/assign.ts

@@ -7,7 +7,7 @@ import { defHttp } from '/@/utils/http/axios'
 
 export class Params {
     /** id */
-    id: number
+    id: string
     /** ids 多个以逗号分割 */
     ids: string
 }

src/api/services/mods/role/deleted.ts

@@ -7,7 +7,7 @@ import { defHttp } from '/@/utils/http/axios'
 
 export class Params {
     /** id */
-    id: number
+    id: string
 }
 
 export const init = new defs.Result()

src/api/services/mods/role/find.ts

@@ -7,7 +7,7 @@ import { defHttp } from '/@/utils/http/axios'
 
 export class Params {
     /** id */
-    id: number
+    id: string
 }
 
 export const init = new defs.Result()

src/api/services/mods/role/index.ts

 /**
- * @description
+ * @description 角色管理
  */
 import * as add from './add'
 import * as assign from './assign'

src/api/services/mods/role/modify.ts

@@ -7,7 +7,7 @@ import { defHttp } from '/@/utils/http/axios'
 
 export class Params {
     /** id */
-    id: number
+    id: string
     /** 名称 */
     name: string
     /** 标识 */

src/api/services/mods/user/assign.ts

@@ -7,7 +7,7 @@ import { defHttp } from '/@/utils/http/axios'
 
 export class Params {
     /** id */
-    id: number
+    id: string
     /** ids 多个以逗号分割 */
     ids: string
 }

src/api/services/mods/user/index.ts

 /**
- * @description
+ * @description 用户管理
  */
 import * as getMenuList from './getMenuList'
 import * as getPermCode from './getPermCode'

src/pages/index/index.vue

@@ -2,7 +2,7 @@
     const title = ref('Hello World')
 
     // TODO: 测试接口
-    API.hello.hello.request().then((body) => {
+    API.example.hello.request().then((body) => {
         console.log(body)
     })
 </script>