Skip to content

Commit

Permalink
Merge pull request #66 from long-woo/dev
Browse files Browse the repository at this point in the history 
v2.0
  • Loading branch information
@long-woo
long-woo committed Aug 28, 2024
2 parents 3f57533 + f2ac3a9 commit 4462d43
Show file tree
Hide file tree
Showing 57 changed files with 1,887 additions and 1,465 deletions.
153 changes: 63 additions & 90 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,9 @@

<p align="center"><img src="resources/stc.svg" alt="logo" /></p>

STC (Swagger Transform Code) is a tool for converting Swagger documents into code files.
[![JSR](https://jsr.io/badges/@loongwoo/stc)](https://jsr.io/@loongwoo/stc)

STC(Swagger Transform Code) 是一个 Swagger 文档转换成代码文件的工具。
STC (Swagger Transform Code) is a tool for converting Swagger(OpenApi) documents into code files.

![Publish to release](https://github.com/long-woo/stc/actions/workflows/deno-build.yml/badge.svg)
[![Publish Package to npmjs](https://github.com/long-woo/stc/actions/workflows/npm.yml/badge.svg)](https://github.com/long-woo/stc/actions/workflows/npm.yml)
Expand All @@ -13,63 +13,36 @@ STC(Swagger Transform Code) 是一个 Swagger 文档转换成代码文件的工
<img src="resources/20240422-151653.gif" alt="stc" />
</div>

feature:
特性：

- 🐹 Support for Swagger 2, 3 and Apifox.

🐹 支持 Swagger 2、3 和 Apifox。

- 🌐 Support Axios, Wechat request library。

🌐 支持 Axios、Wechat 请求库。
## Feature:

- 🐹 Support for Swagger 2/3(OpenApi) and Apifox.
- 💡 Support plug-in development.

💡 支持插件开发。

- 🐣 Built-in transformation languages:

🐣 内置转换语言：

- TypeScript, almost equivalent to handwriting.

TypeScript，几乎等同于手写。

- TypeScript, almost equivalent to handwriting. Depends on **`axios`, `wx.request`, `fetch`**.
> `xhr/ajax、ofetch` planned
- JavaScript, from TypeScript to it.
- Dart, dependency on **`dio`**.
- 🚧 Swift ...

JavaScript，由 TypeScript 转换而来。

- 🚧 ...

## Quick start 快速开始
## Quick start

### Download executable files 下载可执行文件
### Download executable files

[download](https://github.com/long-woo/stc/releases) by system：

按系统[下载](https://github.com/long-woo/stc/releases)：

- stc: Intel-based Mac

stc：Intel 系列的 Mac

- stc-m: M-series Mac

stc-m：M 系列的 Mac

- stc-linux：Linux
- stc-win.exe: Windows

### NPM

1.安装 `@loogwoo/stc` npm 包
1.Install the `@loogwoo/stc` npm package.

```sh
pnpm add @loongwoo/stc -D
```

2.打开项目 `package.json` 文件，在 `scripts` 添加如下命令：
2.Open the project's `package.json` file and add the following command to `scripts`:

```json
{
Expand All @@ -79,12 +52,10 @@ pnpm add @loongwoo/stc -D
}
```

### Use 使用
### Use

⚠️ Note: deno will not parse the `~` character as the user's home directory.

注意：deno 不会解析 `~`字符为用户主目录。

```sh
stc --url=https://petstore3.swagger.io/api/v3/openapi.json --outDir=out
```
Expand All @@ -93,26 +64,26 @@ stc --url=https://petstore3.swagger.io/api/v3/openapi.json --outDir=out

![输出文件](resources/file.png)

### 已有项目
### Existing Project

假设一个项目目录为：
Assume a project directory is:

```
.
├── src
│ └── apis # 将 shared 目录复制到这里
│ └── apis # Copy the shared directory here.
│ └── shared
│ └── xxx.ts # 其他文件
│ └── xxx.ts # Other files.
```

#### Axios

1.找到 `outDir` 的目录，复制 `shared` 整个目录到你封装的 `axios` 模块的目录下。
1. Find the directory of `outDir`, copy the entire `shared` directory to the directory of the `axios` module you encapsulated.

2.打开 `shared > axios > index.ts` 文件，复制 `request` 方法，添加到你封装的 `axios` 模块中。若没有封装的话，复制 `index.ts` 文件为一个新文件，以免修改被覆盖的问题。
2. Open the `shared > axios > index.ts` file, copy the `request` method, and add it to the `axios` module you encapsulated. If it is not encapsulated, copy the `index.ts` file as a new file to avoid the problem of modification being overwritten.

3.以 `Vue` 为例，在 `main.ts` 文件中添加以下代码：
3. Taking `Vue` as an example, add the following code to the `main.ts` file:

```ts
import { createApiClient } from './apis/shared/fetchRuntime';
Expand All @@ -127,11 +98,11 @@ createApiClient({

#### Wechat

1.找到 `outDir` 的目录，复制 `shared` 整个目录到你封装的 `wechat` 模块的目录下。
1. Find the directory of `outDir`, copy the entire directory of `shared` to the directory of the `wechat` module you encapsulated.

2.打开 `shared > wechat > index.ts` 文件，复制 `request` 方法，添加到你封装的 `wx.request` 代码文件中。若没有封装的话，复制 `index.ts` 文件为一个新文件，以免修改被覆盖的问题。
2. Open the `shared > wechat > ​​index.ts` file, copy the `request` method, and add it to the `wx.request` code file you encapsulated. If it is not encapsulated, copy the `index.ts` file as a new file to avoid the problem of modification being overwritten.

3.在 `app.ts` 文件中添加以下代码:
3. Add the following code to the `app.ts` file:

```ts
import { createApiClient } from './apis/shared/fetchRuntime';
Expand All @@ -149,58 +120,60 @@ App<IAppOption>({
});
```

### Options 选项
### Options

| Option | Alias | Type | Default | Description |
| ----------- | ----- | -------- | --------- | ------------------------------------------------------------------------------------------------------------ |
| url | | string | | Swagger 文档地址，或者本地路径 |
| outDir | o | string | ./stc_out | 输出目录 |
| platform | p | string | axios | 平台，可选值：`axios`、`wechat` |
| lang | l | string | ts | 语言，用于输出文件的后缀名 |
| tag | | number | | 从接口 url 指定标签，默认读取 tags 的第一个用于文件名 |
| filter | f | string[] | | 过滤接口，符合过滤条件的接口会被生成。示例: `--filter "/pet/*"`，生成 `/pet` 的接口，同时支持多个 `--filter` |
| conjunction | c | string | By | 方法的连接词，默认值为 `By` |
| version | v | boolean | | 输出版本信息 |
| help | h | boolean | | 输出帮助信息 |

## Plug-in development 插件开发
| url | | string | | Swagger/OpenApi/Apifox document address, or local path. |
| outDir | o | string | ./stc_out | Output Directory. |
| ~~platform~~| p | string | axios | Platform, optional values: `axios`, `wechat`. **Will be deprecated soon, please use `client`.** |
| client | | string | axios | http request client. When `lang` is `ts/js`, the possible values ​​are: `axios`, `wechat`, `fetch`. |
| lang | l | string | ts | Language, used for output file suffix. |
| tag | | number | | Specify the tag from the interface url. By default, the first tag is read for the file name. |
| filter | f | string[] | | Filter interfaces. Interfaces that meet the filter conditions will be generated. Example: `--filter "/pet/*"`, generate an interface for `/pet`, and support multiple `--filter` |
| conjunction | c | string | By | The method's connector, the default value is `By`. |
| version | v | boolean | | Output version information. |
| help | h | boolean | | Output help information. |

## Plug-in development

For convenience, STC can not only develop plugins in Deno, but also provides `@loongwoo/stc` npm library, which can develop plugins in Node environment.

为了方便，STC 不仅可以在 Deno 中开发插件，同时也提供了 `@loongwoo/stc` npm 库，可以在 Node 环境中开发插件。

[查看示例代码](https://github.com/long-woo/stc/tree/master/examples)
[examples](https://github.com/long-woo/stc/tree/master/examples)

### Deno 方式
### Deno

⚠️ 准备 [Deno](https://github.com/denoland/deno#install) 环境
⚠️ Prepare the [Deno](https://github.com/denoland/deno#install) environment.

创建一个 `myPlugin.ts` 文件：
Create a `myPlugin.ts` file:

```ts
// 引用模块
import { start } from 'https://deno.land/x/stc@1.6.4/mod.ts'
import { start } from 'https://deno.land/x/stc@2.0.0/mod.ts'

// 定义插件
// Defining plugins
const myPlugin: IPlugin = {
name: 'stc:MyPlugin',
lang: 'ts',
setup(options) {
console.log(options)
},
onTransform(def, action) {
// 转换 definition
// definition
const defContent: string = parserDefinition(
def /* 这里的 def 是 Definition 对象 */
def
)
// 转换 action
// action
const actionContent: Map<string, string> = parserAction(
action /* 这里的 action 是 Action 对象 */
action
)
// 返回转换后的内容

return {
definition: defContent,
action: actionContent // 这里的 actionContent 是 Map<string, string> 类型，key 是文件名称，value 是转换后的代码
definition: {
filename: '_types.ts',
content: defContent,
},
action: actionContent // Here actionContent is of type Map<string, string>, key is the file name, value is the converted code.
}
},
onEnd() {
Expand All @@ -215,17 +188,17 @@ start({
})
```

### Node 方式
### Node

1.创建一个 `myPlugin.ts` 文件。
1. Create a `myPlugin.ts` file.

2.添加 `@loongwoo/stc` 引用，使用 `start` 方法：
2. Add the `@loongwoo/stc` reference and use the `start` method:

```ts
import { start } from '@loongwoo/stc'
```

3.在插件的 `onTransform` 钩子函数中实现将 `definition` 和 `action` 转换为目标语言的代码。
3. Implement the code that converts `definition` and `action` into the target language in the plugin's `onTransform` hook function.

```ts
export const myPlugin: IPlugin = {
Expand All @@ -235,15 +208,15 @@ export const myPlugin: IPlugin = {
console.log(options)
},
onTransform(def, action) {
// 转换 definition
// definition
const defContent: string = parserDefinition(
def /* 这里的 def 是 Definition 对象 */
def
)
// 转换 action
// action
const actionContent: Map<string, string> = parserAction(
action /* 这里的 action 是 Action 对象 */
action
)
// 返回转换后的内容

return {
definition: defContent,
action: actionContent
Expand All @@ -255,11 +228,11 @@ export const myPlugin: IPlugin = {
}
```

4.在 `start` 方法里，添加 `plugins`:
4.In the `start` method, add `plugins`:

```ts
start({
// ...其他配置
// ...other options
plugins: [myPlugin]
})
```
41 changes: 28 additions & 13 deletions deno.json
View file
Original file line number Diff line number Diff line change
@@ -1,19 +1,17 @@
{
"name": "@loongwoo/stc",
"version": "1.6.4",
"version": "2.0.0",
"exports": "./mod.ts",
"tasks": {
"dev": "deno run -A --watch=src src/main.ts --url 'https://petstore3.swagger.io/api/v3/openapi.json'",
"pack": "deno run -A src/pack.ts",
"dev": "deno task pack && deno run -A --watch=src src/main.ts --url 'https://petstore3.swagger.io/api/v3/openapi.json' --lang dart",
"serve": "deno run -A --watch=src src/service.ts",
"version": "echo '1.6.4' > release/version",
"build:npm": "deno run -A src/npm/index.ts",
"version": "echo '2.0.0' > release/version",
"build:npm": "deno run -A src/npm/build.ts",
"build:mac": "deno compile -A --target x86_64-apple-darwin --output release/stc src/main.ts",
"build:mac-m": "deno compile -A --target aarch64-apple-darwin --output release/stc-m src/main.ts",
"build:win": "deno compile -A --target x86_64-pc-windows-msvc --output release/stc-win src/main.ts",
"build:linux": "deno compile -A --target x86_64-unknown-linux-gnu --output release/stc-linux src/main.ts",
"esm:add": "deno run -A https://esm.sh/v130 add",
"esm:update": "deno run -A https://esm.sh/v130 update",
"esm:remove": "deno run -A https://esm.sh/v130 remove"
"build:win": "deno compile -A --target x86_64-pc-windows-msvc --icon resources/stc.svg --output release/stc-win src/main.ts",
"build:linux": "deno compile -A --target x86_64-unknown-linux-gnu --output release/stc-linux src/main.ts"
},
"lint": {
"include": [
Expand All @@ -23,7 +21,9 @@
"exclude": [
"**/out/**/*",
"**/shared/**/*",
"dist"
"**/template/**/*",
"dist",
"release"
]
},
"fmt": {
Expand All @@ -32,8 +32,11 @@
"test/"
],
"exclude": [
"**/shared/**/*",
"**/template/**/*",
"out/**/*",
"dist"
"dist",
"release"
]
},
"test": {
Expand All @@ -46,5 +49,17 @@
"dist"
]
},
"importMap": "import_map.json"
}
"imports": {
"./": "./",
"/": "./",
"@deno-library/progress": "jsr:@deno-library/progress@^1.4.9",
"@deno/dnt": "jsr:@deno/dnt@^0.41.3",
"@eta-dev/eta": "jsr:@eta-dev/eta@^3.5.0",
"@std/assert": "jsr:@std/assert@^1.0.3",
"@std/cli": "jsr:@std/cli@^1.0.4",
"@std/datetime": "jsr:@std/datetime@^0.225.1",
"@std/fmt": "jsr:@std/fmt@^1.0.1",
"@std/fs": "jsr:@std/fs@^1.0.2",
"x/": "https://deno.land/x/"
}
}
Loading

0 comments on commit 4462d43

Please sign in to comment.