gogoyqj / auto-service Goto Github PK

【+v:skipper_yqj】点个 Star，手有余香, Swagger or YAPI to TypeScript services and models

License: Other

JavaScript 52.19% Shell 0.67% TypeScript 33.81% CSS 2.10% Mustache 7.75% MDX 3.48%

swagger yapi mock typescript services typed sm2tsservice autos

auto-service's Introduction

name	route
指南	/

import logo from './public/assets/logo.png'; import swagger from './public/assets/swagger.png';

Autos

介绍

Autos（automatic Service），根据 Swagger 或者 YApi 格式的接口文档（JSON）自动生成 TypeScript 的接口调用或者类型代码。

Autos 依赖基于开源项目 Swagger Codegen 定制开发的 Java 生成工具，请确保您的平台已经安装 Java。

特性

支持 Swagger 和 YApi 两种格式的接口文档
支持增量更新接口文档数据
支持对接口规范性进行检查
支持仅生成 TypeScript 类型代码
支持所有 Swagger Codegen 的特性，包括自定义 TypeScript 代码模板
支持对接口入参、数据返回进行校验

Autos 是如何工作的？

命名由来

Autos 曾经有一个不那么酷的名字 “sm2tsservice”（Swagger or Mock to TypeScript Service）。

换成 “ Autos”（automatic Service）从字面上能更好被理解、更容易被记住，logo 则蹭一下变形金刚的名气，采用的是 “Autobot(s)” （博派）的标志。

auto-service's People

Contributors

Stargazers

Watchers

auto-service's Issues

V3中camel命名异常，可通过配置 swaggerParse 解决【已解决】

module.exports = {
  "url": "./swagger.json",
  "swaggerParser": {
    "-o": "src/test",
    "-t": "v3/plugins/types-only",
    // "-DmodelPropertyNaming=snake_case": "",
    "-DmodelPropertyNaming=original": "", // 命名与yapi中的保持一致
  },
  "guardConfig": {
    "mode": "strict",
    "validUrlReg": /cungong/g
  }
}

1. 大小写异常 case 【影响小，可忽略】

在 V2/V3中都存在，必现，特别边缘的场景，暂时通过手工修正

2. V3模板 types-only 与 V2 对比，多余文件和 model 比较多，可优化冗余【待解决的小问题】

3. V3模板 types-tkit，存在 _json 目录未生成，造成报错异常【待解决，必现】

4. V3模板下，存在 form-data require异常的问题【应该v3模板的bug】

生成的ts中，require 为 false 的params，也变成了必填项

module.exports = {
  "url": "./swagger.json",
  "swaggerParser": {
    "-DmodelPropertyNaming=original": "",
    "-o": "src/test",
    // "-t": "plugins/types-only" // 存在大小写异常、model未生成的case
    "-t": "v3/plugins/types-only" // 存在大小写异常 required 生成异常
    // "-t": "v3/plugins/typescript-tkit-autos" // 只存在大小写异常
    // "-t": "v3/plugins/types-tkit" // 错误信息：Error: ENOENT: no such file or directory json 找不到
  },
  "guardConfig": {
    "mode": "strict",
    "validUrlReg": /cungong|spamftp/g
  }
}

{
  "swagger": "2.0",
  "info": {
    "title": "unknown",
    "version": "last",
    "description": "unknown"
  },
  "tags": [
    {
      "name": "cungong",
      "description": "cungongDesc"
    }
  ],
  "basePath": "",
  "schemes": [
    "http"
  ],
  "paths": {
    "/cungong/confiltermis/excavateadd": {
      "post": {
        "tags": [
          "cungong"
        ],
        "summary": "任务",
        "description": "",
        "consumes": [
          "multipart/form-data"
        ],
        "parameters": [
          {
            "name": "name",
            "in": "formData",
            "required": true,
            "description": "description",
            "type": "string"
          },
          {
            "name": "command_nos",
            "in": "formData",
            "required": false,
            "description": "description",
            "type": "string"
          },
          {
            "name": "add_type",
            "in": "formData",
            "required": true,
            "description": "description",
            "type": "string"
          },
          {
            "name": "file_url",
            "in": "formData",
            "required": false,
            "description": "description",
            "type": "string"
          },
          {
            "name": "data_status",
            "in": "formData",
            "required": false,
            "description": "description",
            "type": "string"
          },
          {
            "name": "data_rule",
            "in": "formData",
            "required": false,
            "description": "description",
            "type": "string"
          },
          {
            "name": "is_ai",
            "in": "formData",
            "required": false,
            "description": "description",
            "type": "string"
          },
          {
            "name": "start_time",
            "in": "formData",
            "required": false,
            "description": "description",
            "type": "string"
          },
          {
            "name": "end_time",
            "in": "formData",
            "required": false,
            "description": "description",
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "successful operation",
            "schema": {
              "type": "object",
              "title": "CungongConfiltermisExcavateadd",
              "properties": {
                "errNo": {
                  "type": "number"
                },
                "errstr": {
                  "type": "string"
                }
              },
              "required": [
                "errNo",
                "errstr"
              ]
            }
          }
        },
        "operationId": "cungongConfiltermisExcavateaddPost"
      }
    }
  }
}

报错信息：
[ERROR]: gen failed with: [ERROR]: gen failed from
/Users/didi/learn/auto-service-test/node_modules/auto-service/tmp/ac203f6cf913d4055f5c955a3fee96f9.json with
访问临时目录 /Users/didi/learn/auto-service-test/node_modules/auto-service/tmp/ac203f6cf913d4055f5c955a3fee96f9_json 失败
错误信息：Error: ENOENT: no such file or directory, scandir '/Users/didi/learn/auto-service-test/node_modules/auto-service/tmp/ac203f6cf913d4055f5c955a3fee96f9_json'

auto-service 版本：4.0.9

Service 带查询参数生成有误？

刚从 [email protected] 升级到 4.0.1，之前的一个 service 调用为：

APIS.ShareApi.apiV1ShareFindProjectByShareLinkShareUuidGet

看了一下现在生成的是 apiV1ShareFindProjectByShareLinkshareUuidGet，查询参数没有 upper case 一下？

能否指定Ajax 接口导入的名称 @ajax

Hi，大佬们

能不能指定
import ajax, { AjaxPromise, ExtraFetchParams } from '@Ajax';

'@Ajax' 这个名称啊？

换成

import ajax, { AjaxPromise, ExtraFetchParams } from '@AJAX11111';

维护的多个接口，需要不同的ajax，不适合写在一起

[New Featrue] 支持自定义 Header 字段生成参数可选

看到之前版本是有源代码公开的
现在不公开是为什么？

yapi枚举值如果有中文，生成的ts代码中key为空

你好，

我们项目中使用的yapi定义了枚举，如图，其中有中文字符，和英文+中文字符

但是生成的ts代码中，纯中文的enum生成的key为空，期望可以key，value值相同

openapi support ?

hi~, thanks for this tool, it's very helpful to me!

but i got some error when i'm using this tool with openapi

run this command

> npx autos --quiet --models

and got the following error:

Exception in thread "main" java.lang.RuntimeException: missing swagger input or config!
        at io.swagger.codegen.DefaultGenerator.generate(DefaultGenerator.java:747)
        at io.swagger.codegen.cmd.Generate.run(Generate.java:285)
        at io.swagger.codegen.SwaggerCodegen.main(SwaggerCodegen.java:35)

the api.json looks like this:

{
  "openapi": "3.0.3",
  "info": {
    "title": "中台微服务-接口文档",
    "description": "中台微服务",
    "version": "1.0"
  },
  "server": {
     // .....
   },
   "tags": {
     // ....
    },
   "paths": {
     // ....
    },
   "components": {
     // ....
    },
}

Looking forward to your reply :)

文档有问题，刷新404

https://gogoyqj.github.io/auto-service/getting-started

如上

怎么运行，有具体的文档吗

如何解决『可能编写错误或废弃，请联系接口方修改』

【错误】接口 "post /official_account/refresh_auth_token/:app_id" "path" 参数 "app_id" "" 可能编写错误或废弃，请联系接口方修改
【错误】接口 "post /material/permanent/delete/:appID/:mediaID" "path" 参数 "appID" "" 可能编写错误或废弃，请联系接口方修改
【错误】接口 "post /material/permanent/delete/:appID/:mediaID" "path" 参数 "mediaID" "" 可能编写错误或废弃，请联系接口方修改
【错误】接口 "get /material/temporary/get/:appID/:mediaID" "path" 参数 "appID" "" 可能编写错误或废弃，请联系接口方修改
【错误】接口 "get /material/temporary/get/:appID/:mediaID" "path" 参数 "mediaID" "" 可能编写错误或废弃，请联系接口方修改
【错误】接口 "get /material/count/:appID" "path" 参数 "appID" "" 可能编写错误或废弃，请联系接口方修改
【错误】接口 "delete /push_template/:id" "path" 参数 "id" "" 可能编写错误或废弃，请联系接口方修改
【错误】接口 "get /push_template/get/:id" "path" 参数 "id" "" 可能编写错误或废弃，请联系接口方修改
【错误】接口 "delete /push_plan/:id" "path" 参数 "id" "" 可能编写错误或废弃，请联系接口方修改

这些错误都是像这样的设置

不知道该如何处理

增量更新无法全选

建议支持修改 host 或使用 localhost

WSL 下通过浏览器 127.0.0.1 不可访问 WSL 下的服务，需要改为 localhost 才行，已经改累了 _(:з」∠)_

response schema 中如果存在 additionalProperties 参数，生成的 ts 文件返回类型全是 AjaxPromise<{ [key: string]: any }>

{
  "info": {
    "title": "Test swagger",
    "description": "Testing the Fastify swagger API",
    "version": "0.1.0"
  },
  "paths": {
    "/api/method1": {
      "get": {
        "summary": "egg-like controller method1",
        "description": "egg-like controller method1",
        "parameters": [
          {
            "name": "encryptedData",
            "type": "string",
            "description": "测试",
            "default": "2",
            "require": true,
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "schema": {
              "type": "object",
              "properties": {
                "status": {
                  "type": "string"
                },
                "result": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "number",
                      "enum": [
                        "SUCCESS",
                        "ERR_PARAM",
                        "NOT_WECHAT_AUTH",
                        "NOT_LOGIN",
                        "ERROR",
                        "FAIL_UPLOAD"
                      ]
                    },
                    "msg": {
                      "type": "string"
                    },
                    "data": {
                      "type": "object",
                      "properties": {},
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "code",
                    "msg",
                    "data"
                  ],
                  "additionalProperties": false
                }
              },
              "required": [
                "status"
              ],
              "additionalProperties": false
            }
          },
          "400": {
            "schema": {
              "type": "object",
              "properties": {
                "status": {
                  "type": "string"
                },
                "result": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "number",
                      "enum": [
                        "SUCCESS",
                        "ERR_PARAM",
                        "NOT_WECHAT_AUTH",
                        "NOT_LOGIN",
                        "ERROR",
                        "FAIL_UPLOAD"
                      ]
                    },
                    "msg": {
                      "type": "string"
                    },
                    "data": {
                      "type": "object",
                      "properties": {},
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "code",
                    "msg",
                    "data"
                  ],
                  "additionalProperties": false
                }
              },
              "required": [
                "status"
              ],
              "additionalProperties": false
            }
          }
        },
        "tags": [
          "Egg"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ]
      }
    },
    "/api/method2": {
      "post": {
        "summary": "egg-like controller method1",
        "description": "egg-like controller method1",
        "parameters": [
          {
            "name": "data",
            "description": "request body",
            "schema": {
              "type": "object",
              "properties": {
                "encryptedData": {
                  "type": "string",
                  "description": "测试",
                  "default": "2",
                  "require": true
                }
              }
            },
            "in": "body"
          }
        ],
        "responses": {
          "200": {
            "description": "success",
            "schema": {
              "type": "object",
              "properties": {
                "status_code": {
                  "type": "number",
                  "description": "fdsfsdfdsfds"
                },
                "data": {
                  "type": "object"
                },
                "message": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "schema": {
              "type": "object",
              "properties": {
                "encryptedData": {
                  "type": "string",
                  "description": "测试",
                  "default": "2"
                }
              },
              "required": [
                "encryptedData"
              ],
              "additionalProperties": false
            }
          }
        },
        "tags": [
          "Egg"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ]
      }
    }
  },
  "responses": {},
  "definitions": {},
  "tags": [
    {
      "name": "user",
      "description": "User related end-points"
    }
  ],
  "swagger": "2.0",
  "securityDefinitions": {
    "api_key": {
      "type": "apiKey",
      "name": "Authorization",
      "in": "header"
    },
    "swagger_auth": {
      "type": "oauth2",
      "authorizationUrl": "http://swagger.io/api/oauth/dialog",
      "flow": "implicit",
      "scopes": {
        "write:homes": "modify home info",
        "read:homes": "read home info"
      }
    }
  },
  "allowUnknown": true,
  "externalDocs": {
    "url": "https://swagger.io",
    "description": "Find more info here"
  },
  "host": "127.0.0.1:7001",
  "schemes": [
    "http",
    "https"
  ],
  "consumes": [
    "application/json"
  ],
  "produces": [
    "application/json"
  ],
  "security": [
    {
      "api_key": []
    }
  ]
}

response schema 中如果存在 additionalProperties 参数，生成的 ts 文件返回类型全是 AjaxPromise<{ [key: string]: any }>
删除所有 additionalProperties 就没问题

public apiMethod1Get = (
    params: ParamsapiMethod1Get,
    opt?: ExtraFetchParams
  ): AjaxPromise<{ [key: string]: any }> => {
    const url = this.$basePath + `/api/method1`;
    const p: any = {};
    p.query = {};
    if ('encryptedData' in params) p.query.encryptedData = params.encryptedData;
    return ajax.ajax({
      ...opt,
      method: 'GET',
      url,
      ...p
    });
  };

mac 运行直接报错？

如图，不管是在项目下运行 `npx auto -c ./json2server.json` 命令，还是在外层运行 `npx auto -v`，都会报错

swagger 3.0爆错，看起来是脚本中自动删掉了那个目录，手动创建目录也说找不到

➜ npx autos
[INFO]: 打开链接 http://127.0.0.1:3007/ 编辑
[ERROR]: gen failed with: [ERROR]: gen failed from
/usr/local/lib/node_modules/auto-service/tmp/1ea9c3379bc5fe5674e8665d17eb41e9.json with
访问临时目录 /usr/local/lib/node_modules/auto-service/tmp/1ea9c3379bc5fe5674e8665d17eb41e9_json 失败
错误信息：Error: ENOENT: no such file or directory, scandir '/usr/local/lib/node_modules/auto-service/tmp/1ea9c3379bc5fe5674e8665d17eb41e9_json'

@ajax 如何设置才能引用到？

大佬你好，我不太清楚如何设置才能正确引用 @Ajax 模块，ts 总是报错。谢谢大佬~

modle文件缺失

1.当我单独定义include指定路径时， body和返回体的类型文件生成正常
2.当我include指定多个路径时，部分路径只生成返回体或者只生成body的modle类型文件

是否支持生成接口返回的数据的ts类型？

是否支持生成接口返回的数据的ts类型？生成的ts类型直接克引入使用

【通告】技术讨论需求群

wx 加 skipper_yqj 进群

带path-parameters路径的GET和POST方法，如果POST的Body和GET的Response中存在相同名称的对象，生成的model有问题（其他）

path-parameters
/test/{index} 的 get接口的 response 存在test名称的对象
/test/{index} 的 post接口的 Body 也存在test名称的对象

swagger.json 如下
{ "swagger": "2.0", "info": { "title": "unknown", "version": "last", "description": "unknown" }, "basePath": "", "tags": [ { "name": "公共分类", "description": "公共分类" } ], "schemes": [ "http" ], "paths": { "/test/{index}": { "get": { "tags": [ "公共分类" ], "summary": "testGet", "description": "", "parameters": [ { "name": "index", "in": "path", "description": "", "required": true, "type": "string" } ], "responses": { "200": { "description": "successful operation", "schema": { "type": "object", "properties": { "test": { "type": "object", "properties": { "get": { "type": "string" } }, "required": [ "get" ] } }, "required": [ "test" ], "title": "TestIndex" } } } }, "post": { "tags": [ "公共分类" ], "summary": "testPost", "description": "", "consumes": [ "application/json" ], "parameters": [ { "name": "index", "in": "path", "description": "", "required": true, "type": "string" }, { "name": "TestIndexBody", "in": "body", "schema": { "type": "object", "properties": { "test": { "type": "object", "properties": { "post": { "type": "string" } }, "required": [ "post" ] } }, "required": [ "test" ] } } ], "responses": { "200": { "description": "successful operation", "schema": { "type": "object", "title": "title", "properties": {} } } } } } } }

这种情况下，生成的model有问题
model 中 get的test 是 models.TestIndexTest 类型， model中定义的类型是 TestindexTest。注意大小写，是不一样的，如下图

这个定义的TestindexTest，是post中的test的类型，也不是get中test字段的类型。

【最佳实践】多分支并行开发情况下如何merge swagger.json？

背景：

在生成 swagger.json 文件时差异太多，不清楚该如何操作。
在合并 master 代码时 swagger.json 文件冲突过多，不知该如何解决。

方法步骤建议：

合并 master 时,直接用 mater 上的 api 文件覆盖本地文件
1-1. git checkout master ./swagger.json ./src/service
1-2. git merge master
对应后端发布分支合并master，生成最新 swagger
sm2tsservice remoteUrl 指向后端发布分支对应的最新 swagger
npm run api

【通告】3.2.1 - 3.2.3 版本处理 swagger 的bug

使用 3.2.1 - 3.2.3 版本的，由于存在以下bug

mode: strict 处理 swagger 的时候，不能正确生成唯一 operationId

请升级到 3.2.5

[ERROR]: 基于 YAPI 生成失败: [ERROR]: parse yapi to swagger from https://sr-yapi.woa.com/api/open/plugin/export-full?type=json&pid=148&status=all&token=1168b3818b0d334d16e3605afab5a9a4becc41b80ef2fb7eacebfd4efa03b048 faild with Cannot read properties of undefined (reading 'errcode')
1

基本配置

{
  "url": "yapi-swagger.json",
  "remoteUrl": "https://sr-yapi.woa.com/api/open/plugin/export-full?type=json&pid=148&status=all&token=1168b3818b0d334d16e3605afab5a9a4becc41b80ef2fb7eacebfd4efa03b048",
  "type": "yapi",
  "swaggerParser": {}
}

npx autos -c yapi-swagger-json2service.json --clear --models

fomater 不生效

{
  swaggerConfig: {
    formater: 'npx prettier {path}/**/**.ts --write --log-level error --with-node-modules'
  },
}

不能生效没有格式化代码

【最佳实践】基于 Java 的 Swagger 注解规范

见 https://juejin.im/post/5f153ef3e51d4534be06d9ba swagger 规范章节