diff --git a/.github/workflows/docker.yaml b/.github/workflows/docker.yaml index 03ab68e..78369c2 100644 --- a/.github/workflows/docker.yaml +++ b/.github/workflows/docker.yaml @@ -17,7 +17,7 @@ jobs: uses: docker/metadata-action@v3 with: images: | - gotomicro/egogen + gotomicro/eapi tags: | type=schedule type=ref,event=branch diff --git a/.gitignore b/.gitignore index 05d6d5c..e324837 100644 --- a/.gitignore +++ b/.gitignore @@ -8,5 +8,4 @@ logs bin/ bak -ego-gen-api tmpls/dist \ No newline at end of file diff --git a/Dockerfile b/Dockerfile index fc11f51..e2fb709 100644 --- a/Dockerfile +++ b/Dockerfile @@ -10,7 +10,7 @@ WORKDIR /data COPY go.mod go.sum ./ RUN go mod download -x COPY . . -RUN go build -o ./bin/egogen cmd/egogen/egogen.go +RUN go build -o ./bin/eapi cmd/eapi/eapi.go # Fianl running stage FROM golang:1.18.3-alpine3.16 @@ -18,7 +18,7 @@ LABEL maintainer="goproxy@gotomicro.com" WORKDIR /data -COPY --from=go-builder /data/bin/egogen /bin/ +COPY --from=go-builder /data/bin/eapi /bin/ RUN sed -i 's/dl-cdn.alpinelinux.org/mirrors.aliyun.com/g' /etc/apk/repositories -CMD ["sh", "-c", "/bin/egogen"] +CMD ["sh", "-c", "/bin/eapi"] diff --git a/Makefile b/Makefile index c3c56e0..f71ce0c 100644 --- a/Makefile +++ b/Makefile @@ -1,4 +1,4 @@ .PHONY: build build: - @go build -o ./bin/egogen cmd/egogen/egogen.go + @go build -o ./bin/eapi cmd/eapi/eapi.go diff --git a/README.md b/README.md index afb451c..b05c411 100644 --- a/README.md +++ b/README.md @@ -1,22 +1,22 @@ -# ego-gen [WIP] +# eapi -`ego-gen-api` 通过分析 AST 解析出代码中的路由（方法/路径）和 Handler 函数（请求响应参数/响应状态码等）获取接口的信息，进而生成 Swagger 文档。 +EAPI 是一个通过分析 AST 生成 **接口文档** 及 **前端接口请求代码** 的命令行工具。作为 swaggo 等工具的替代品，EAPI 无需编写复杂的注解即可使用。 -由于本工具只分析 AST 中的关键部分（类似于静态分析）而不执行代码，因此并不能覆盖到任一种使用场景。如果你要在项目中使用本工具，必须要按照一定的约定编写代码，否则将不能生成完整的文档。虽然这给你的代码编写带来了一定的约束，但从另一个角度看，这也使得代码风格更加统一。 +eapi 通过分析 AST 解析出代码中的路由（方法/路径）和 Handler 函数（请求响应参数/响应状态码等）获取接口的信息，进而生成 OpenAPI(Swagger) 文档。eapi 目前支持了 gin 框架的文档生成，echo 等其他主流框架在计划中。如果你需要将 eapi 应用在其他未被支持的框架，可以通过编写自定义插件的方式进行实现，或者给我们提交 PR。 -本工具目前支持了 `gin` 框架的文档生成。如果你需要将本项目进行扩展或应用于未支持的框架，可以通过编写自定义插件的方式进行实现。 +由于本工具只分析 AST 中的关键部分（类似于静态分析）而不执行代码，因此如果你要在项目中使用本工具，必须要按照一定的约定编写代码，否则将不能生成完整的文档。虽然这给你的代码编写带来了一定的约束，但从另一个角度看，这也使得代码风格更加统一。 ## 安装 Install > goproxy 可能会存在缓存，可以优先尝试指定版本号进行安装。 > ```shell -go install github.com/gotomicro/ego-gen-api/cmd/egogen@latest +go install github.com/gotomicro/eapi/cmd/eapi@latest ``` -## 如何使用 How to Use +## 如何使用 ### 通过配置文件 -**egogen.yaml**: +**eapi.yaml**: ```yaml output: docs plugin: gin @@ -26,14 +26,14 @@ dir: 'api' # 需要解析的代码根目录 在代码根目录下执行: ```shell -egogen --config egogen.yaml +eapi --config eapi.yaml ``` ### 通过命令行参数 在代码根目录下执行: ```shell -egogen --output docs --plugin gin --dir api +eapi --output docs --plugin gin --dir api ``` 执行以上命令后，会在 `/docs` 目录下生成 `swagger.json` 文件。 @@ -114,3 +114,6 @@ generators: - name: ts output: ./src/types # 输出文件的目录 ``` + +# TODO +- [ ] support for `echo` framework diff --git a/analyzer.go b/analyzer.go index 7cb8e92..85a2d72 100644 --- a/analyzer.go +++ b/analyzer.go @@ -1,4 +1,4 @@ -package analyzer +package eapi import ( "fmt" @@ -9,7 +9,7 @@ import ( "path/filepath" "strings" - "github.com/gotomicro/ego-gen-api/spec" + "github.com/gotomicro/eapi/spec" "github.com/knadh/koanf" "github.com/samber/lo" "golang.org/x/mod/modfile" diff --git a/cmd/egogen/egogen.go b/cmd/eapi/eapi.go similarity index 53% rename from cmd/egogen/egogen.go rename to cmd/eapi/eapi.go index 3f9d532..f7fa193 100644 --- a/cmd/egogen/egogen.go +++ b/cmd/eapi/eapi.go @@ -3,8 +3,8 @@ package main import ( "os" - analyzer "github.com/gotomicro/ego-gen-api" - "github.com/gotomicro/ego-gen-api/plugins/gin" + analyzer "github.com/gotomicro/eapi" + "github.com/gotomicro/eapi/plugins/gin" ) func main() { diff --git a/comment.go b/comment.go index 39b78dc..d34809f 100644 --- a/comment.go +++ b/comment.go @@ -1,11 +1,11 @@ -package analyzer +package eapi import ( "go/ast" "strings" - "github.com/gotomicro/ego-gen-api/annotation" - "github.com/gotomicro/ego-gen-api/spec" + "github.com/gotomicro/eapi/annotation" + "github.com/gotomicro/eapi/spec" "github.com/samber/lo" ) diff --git a/context.go b/context.go index 2fb7085..81ad5aa 100644 --- a/context.go +++ b/context.go @@ -1,4 +1,4 @@ -package analyzer +package eapi import ( "fmt" @@ -7,7 +7,7 @@ import ( "go/types" "strconv" - "github.com/gotomicro/ego-gen-api/spec" + "github.com/gotomicro/eapi/spec" "golang.org/x/tools/go/packages" ) diff --git a/definition.go b/definition.go index 65141c5..0b44f8c 100644 --- a/definition.go +++ b/definition.go @@ -1,11 +1,11 @@ -package analyzer +package eapi import ( "fmt" "go/ast" "strings" - "github.com/gotomicro/ego-gen-api/spec" + "github.com/gotomicro/eapi/spec" "golang.org/x/tools/go/packages" ) diff --git a/entrypoint.go b/entrypoint.go index f9804e5..51cba95 100644 --- a/entrypoint.go +++ b/entrypoint.go @@ -1,4 +1,4 @@ -package analyzer +package eapi import ( "encoding/json" @@ -8,8 +8,8 @@ import ( "os" "path/filepath" - _ "github.com/gotomicro/ego-gen-api/generators/ts" - _ "github.com/gotomicro/ego-gen-api/generators/umi" + _ "github.com/gotomicro/eapi/generators/ts" + _ "github.com/gotomicro/eapi/generators/umi" "github.com/knadh/koanf" "github.com/knadh/koanf/parsers/yaml" "github.com/knadh/koanf/providers/file" @@ -47,14 +47,14 @@ func NewEntrypoint(plugins ...Plugin) *Entrypoint { } const usageText = `Generate Doc: - egogen --config config.yaml + eapi --config config.yaml or - egogen --plugin gin --dir src/ --output docs/ + eapi --plugin gin --dir src/ --output docs/ Generate Frontend Code: - egogen --config config.yaml gencode + eapi --config config.yaml gencode or - egogen --plugin gin --dir src/ --output docs/ gencode` + eapi --plugin gin --dir src/ --output docs/ gencode` func (e *Entrypoint) Run(args []string) { app := cli.NewApp() diff --git a/environment.go b/environment.go index 8d2b88f..281ea57 100644 --- a/environment.go +++ b/environment.go @@ -1,4 +1,4 @@ -package analyzer +package eapi type Environment struct { parent *Environment diff --git a/generator_executor.go b/generator_executor.go index 50e50b8..164c277 100644 --- a/generator_executor.go +++ b/generator_executor.go @@ -1,12 +1,12 @@ -package analyzer +package eapi import ( "fmt" "os" "path/filepath" - "github.com/gotomicro/ego-gen-api/generators" - "github.com/gotomicro/ego-gen-api/spec" + "github.com/gotomicro/eapi/generators" + "github.com/gotomicro/eapi/spec" ) type generatorExecutor struct { diff --git a/generators/generators.go b/generators/generators.go index 140f79a..0f1189e 100644 --- a/generators/generators.go +++ b/generators/generators.go @@ -1,6 +1,6 @@ package generators -import "github.com/gotomicro/ego-gen-api/spec" +import "github.com/gotomicro/eapi/spec" type Generator struct { Type string diff --git a/generators/ts/ts.go b/generators/ts/ts.go index 1f14a41..9fc1df4 100644 --- a/generators/ts/ts.go +++ b/generators/ts/ts.go @@ -3,9 +3,9 @@ package ts import ( _ "embed" - f "github.com/gotomicro/ego-gen-api/formatter" - "github.com/gotomicro/ego-gen-api/generators" - "github.com/gotomicro/ego-gen-api/spec" + f "github.com/gotomicro/eapi/formatter" + "github.com/gotomicro/eapi/generators" + "github.com/gotomicro/eapi/spec" "github.com/samber/lo" ) diff --git a/generators/umi/umi.go b/generators/umi/umi.go index d902768..4bf53bd 100644 --- a/generators/umi/umi.go +++ b/generators/umi/umi.go @@ -7,10 +7,10 @@ import ( "sort" "strings" - f "github.com/gotomicro/ego-gen-api/formatter" - "github.com/gotomicro/ego-gen-api/generators" - "github.com/gotomicro/ego-gen-api/generators/ts" - "github.com/gotomicro/ego-gen-api/spec" + f "github.com/gotomicro/eapi/formatter" + "github.com/gotomicro/eapi/generators" + "github.com/gotomicro/eapi/generators/ts" + "github.com/gotomicro/eapi/spec" "github.com/iancoleman/strcase" "github.com/samber/lo" ) diff --git a/go.mod b/go.mod index 8c79def..77b7660 100644 --- a/go.mod +++ b/go.mod @@ -1,4 +1,4 @@ -module github.com/gotomicro/ego-gen-api +module github.com/gotomicro/eapi go 1.18 diff --git a/mod.go b/mod.go index 05d5042..dde97f8 100644 --- a/mod.go +++ b/mod.go @@ -1,4 +1,4 @@ -package analyzer +package eapi import ( "golang.org/x/mod/modfile" diff --git a/param_parser.go b/param_parser.go index fd861ea..c85a304 100644 --- a/param_parser.go +++ b/param_parser.go @@ -1,11 +1,11 @@ -package analyzer +package eapi import ( "go/ast" "go/types" - "github.com/gotomicro/ego-gen-api/spec" - "github.com/gotomicro/ego-gen-api/tag" + "github.com/gotomicro/eapi/spec" + "github.com/gotomicro/eapi/tag" ) type ParamParser struct { diff --git a/plugin.go b/plugin.go index 52f4a43..4de15dd 100644 --- a/plugin.go +++ b/plugin.go @@ -1,4 +1,4 @@ -package analyzer +package eapi import ( "go/ast" diff --git a/plugins/gin/gin.go b/plugins/gin/gin.go index 305522d..3e52c38 100644 --- a/plugins/gin/gin.go +++ b/plugins/gin/gin.go @@ -8,7 +8,7 @@ import ( "regexp" "strings" - analyzer "github.com/gotomicro/ego-gen-api" + analyzer "github.com/gotomicro/eapi" "github.com/knadh/koanf" ) diff --git a/plugins/gin/gin_test.go b/plugins/gin/gin_test.go index 9183075..37d2a99 100644 --- a/plugins/gin/gin_test.go +++ b/plugins/gin/gin_test.go @@ -6,7 +6,7 @@ import ( "runtime" "testing" - analyzer "github.com/gotomicro/ego-gen-api" + analyzer "github.com/gotomicro/eapi" "github.com/knadh/koanf" "github.com/knadh/koanf/parsers/yaml" "github.com/knadh/koanf/providers/file" diff --git a/plugins/gin/handler_analyzer.go b/plugins/gin/handler_analyzer.go index 5a487a7..780d9ea 100644 --- a/plugins/gin/handler_analyzer.go +++ b/plugins/gin/handler_analyzer.go @@ -7,8 +7,8 @@ import ( "net/http" "strings" - analyzer "github.com/gotomicro/ego-gen-api" - "github.com/gotomicro/ego-gen-api/spec" + analyzer "github.com/gotomicro/eapi" + "github.com/gotomicro/eapi/spec" "github.com/iancoleman/strcase" "github.com/robertkrimen/otto" "github.com/samber/lo" diff --git a/plugins/gin/testdata/server/docs/swagger.json b/plugins/gin/testdata/server/docs/swagger.json index bcd59b5..cbe37ab 100755 --- a/plugins/gin/testdata/server/docs/swagger.json +++ b/plugins/gin/testdata/server/docs/swagger.json @@ -346,9 +346,9 @@ } }, "required": [ + "msg", "data", - "code", - "msg" + "code" ], "type": "object" } diff --git a/route.go b/route.go index 0005ef8..744c452 100644 --- a/route.go +++ b/route.go @@ -1,11 +1,11 @@ -package analyzer +package eapi import ( "go/ast" "net/http" "strings" - "github.com/gotomicro/ego-gen-api/spec" + "github.com/gotomicro/eapi/spec" ) type RouteGroup struct { diff --git a/schema.go b/schema.go index 96f1c39..1365078 100644 --- a/schema.go +++ b/schema.go @@ -1,4 +1,4 @@ -package analyzer +package eapi import ( "fmt" @@ -6,8 +6,8 @@ import ( "go/types" "strings" - "github.com/gotomicro/ego-gen-api/spec" - "github.com/gotomicro/ego-gen-api/tag" + "github.com/gotomicro/eapi/spec" + "github.com/gotomicro/eapi/tag" "github.com/samber/lo" ) diff --git a/stack.go b/stack.go index 25597f9..4f4461b 100644 --- a/stack.go +++ b/stack.go @@ -1,4 +1,4 @@ -package analyzer +package eapi type Stack[T any] []T diff --git a/utils.go b/utils.go index 33656ab..75baaa8 100644 --- a/utils.go +++ b/utils.go @@ -1,4 +1,4 @@ -package analyzer +package eapi import ( "io/ioutil"